{configured webhook URL}Webhook payloads
Endpoint shape implemented by external webhook receivers. Return any 2xx response after accepting an event. - Delivery is at least once. Deduplicate on the `webhook-id` header, which equals the payload `id` and stays the same on every retry of an event. The body is identical on every retry. - Delivery order isn't guaranteed, even within one conversation. For `message.updated`, keep the snapshot with the highest `message.revision`. - Each attempt times out after 15 seconds. Any 2xx response acknowledges the event. Redirects aren't followed. - Timeouts, connection errors, 3xx, 408, 429 and 5xx responses are retried about 30 seconds, 5 minutes and 30 minutes after the first attempt, for 4 attempts in total. Retry times include up to 20% random jitter, and the last retry happens within 30 minutes of the first attempt. - After a 429, a `Retry-After` value in seconds makes the next attempt wait at least that long. If that is later than 30 minutes after the first attempt, the event isn't retried. - 410 and any other 4xx response stop retries for that event. - An event that isn't delivered after its last attempt isn't sent again. Flownally never disables the endpoint automatically. - `webhook-timestamp` and `webhook-signature` are generated again for each attempt. - `GET /webhooks/attempts` lists delivery attempts from the last 7 days. - Events are delivered only while the webhook is enabled and verified. Changing `url` clears `verified`; deliveries resume after `POST /webhooks:verify` succeeds for the saved URL. Events from the time in between aren't delivered later.
Authorization
Scheme
- standardWebhooks
External receiver endpoint shape for webhook events.
Parameters
- Name
Webhook-Id- Type
- header string
- Description
- Event identifier. Equals the payload `id` and stays the same on every retry of the event. Deduplicate deliveries with this value.
- Name
Webhook-Timestamp- Type
- header integer
- Description
- Unix timestamp in seconds for this delivery attempt; it changes on each retry. Reject stale timestamps to prevent replay.
- Name
Webhook-Signature- Type
- header string
- Description
- Standard Webhooks signature header, generated for each attempt. Verify it against `webhook-id`, `webhook-timestamp`, and the exact raw request body.
Request body
- Name
application/json- Type
- WebhookPayload
- Description
- Required body.
Payload variants
- Name
contact.created- Type
- ContactCreatedWebhookEvent
- Description
- Name
contact.updated- Type
- ContactUpdatedWebhookEvent
- Description
- Name
contact.archived- Type
- ContactArchivedWebhookEvent
- Description
- Name
conversation.started- Type
- ConversationStartedWebhookEvent
- Description
- A session started in a conversation. Sent once per session, when its first customer message or human agent's message arrives. Outbound automated messages (API, journey, campaign or desk) sent while the conversation has no active session start no session; they are delivered without one. A conversation can have many sessions over its lifetime.
- Name
conversation.updated- Type
- ConversationUpdatedWebhookEvent
- Description
- An open session's status or owner changed; `changedFields` lists what changed, and changes that aren't visible in the payload (such as team access) send nothing. For example, a chatbot handing a session over to agents sends this event with `changedFields` `["status", "owner"]` and `session.status` `pending`. Starting and closing a session send `conversation.started` and `conversation.closed` instead, so `session.status` is never `closed` here.
- Name
conversation.closed- Type
- ConversationClosedWebhookEvent
- Description
- A session closed. Sent once for every session that closes; `session.started` is `false` for a session no customer or human agent wrote in. A closed session is never reopened; the next message starts a new session in the same conversation.
- Name
message.created- Type
- MessageCreatedWebhookEvent
- Description
- Name
message.updated- Type
- MessageUpdatedWebhookEvent
- Description
- Name
webhook.test- Type
- WebhookTestEvent
- Description
- Sent only by `POST /webhooks:verify` to confirm the endpoint. Respond with any 2xx. Carries no business data.
Responses
- 2XX
Event accepted