Skip to content
DutiesBook API
Open app

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.

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.

id string
Event ID. Deduplicate on this — a redelivered event keeps the same id.
type string
meta_flow.completed or meta_flow.undelivered
occurredAt string
When the customer acted (not when we emitted the webhook)
live boolean
False for a Test click or a draft-mode preview send
data.metaFlowId string
Meta's Flow ID
data.sendId string
The ID returned as sendId from /messages/send or a bulk personalization
data.state string
Your correlation token from flow.state, if you set one
data.contactId string
The contact's UUID in your organization
data.conversationId string
The conversation's UUID in your organization
data.waId string
The customer's WhatsApp ID, passed through from Meta
data.submission object
Present only on meta_flow.completed
data.failure object
Present only on meta_flow.undelivered — { category, retryable, metaCode, metaTitle }

Every delivery carries these headers:

X-Dutiesbook-Event
Event type
X-Dutiesbook-Event-Id
Same as body.id
X-Dutiesbook-Delivery
Unique per delivery attempt
X-Dutiesbook-Attempt
Attempt number, starting at 1
X-Dutiesbook-Timestamp
Unix seconds the request was signed
X-Dutiesbook-Signature
Comma-separated list of v1=<hex> signatures, newest key first
X-Dutiesbook-Signature-Keys
Fingerprints matching each signature, for logging which key verified

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.