Flow events
When a customer completes a WhatsApp Flow (started from a template sent via Send Message or Bulk Messaging), we push a webhook to a URL configured on your channel.
Configuring the webhook URL
The webhook endpoint itself (URL, secret, active/inactive) is configured per channel in your dashboard, not through the External API. Everything below assumes a webhook is already configured and receiving deliveries.
The webhook payload
Section titled “The webhook payload”Each completion (or failure) posts one JSON body to your configured URL:
{ "id": "evt_abc123", "type": "meta_flow.completed", "occurredAt": "2024-01-15T10:31:00.000Z", "live": true, "organizationId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "webhookId": "wh_abc123", "channelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "data": { "metaFlowId": "1234567890", "sendId": "fsend_abc123xyz", "state": "order-58212", "contactId": "contact-uuid", "conversationId": "conversation-uuid", "waId": "1234567890", "channelPhoneNumber": "+1234567890", "submission": { "screen_0_Full_name_0": "John Doe", "screen_0_Preferred_time_1": "Mon 10am" } }}meta_flow.completed
The customer submitted the last screen. Carries data.submission — the customer’s raw answers, keyed by Meta’s own field names.
meta_flow.undelivered
The Flow never reached the customer’s handset. No submission field — it’s absent, not empty.
Presence is normative, forever
The payload has no version field — its compatibility promise is additive-only: keys are never renamed, moved, or retyped. submission keys are Meta’s own field names, passed through verbatim; they’re deliberately not normalized to friendlier names.
Payload fields
Section titled “Payload fields”id string type string meta_flow.completed or meta_flow.undeliveredoccurredAt string live boolean data.metaFlowId string data.sendId string sendId from /messages/send or a bulk personalizationdata.state string flow.state, if you set onedata.contactId string data.conversationId string data.waId string data.submission object meta_flow.completeddata.failure object meta_flow.undelivered — { category, retryable, metaCode, metaTitle }Verifying the signature
Section titled “Verifying the signature”Every delivery carries these headers:
X-Dutiesbook-Event X-Dutiesbook-Event-Id X-Dutiesbook-Delivery X-Dutiesbook-Attempt X-Dutiesbook-Timestamp X-Dutiesbook-Signature v1=<hex> signatures, newest key firstX-Dutiesbook-Signature-Keys Recompute and compare:
signature = HMAC-SHA256(secret, "v1:" + eventId + ":" + timestamp + ":" + rawBody)Rotation
During a secret rotation, two signatures are sent (newest first) so you can verify against either your old or new stored secret without downtime.