{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: either the message creates the session, or it arrives in a session that so far has only outbound automated messages. A session created `cold` by an outbound automated message (API, journey, campaign or chatbot) doesn't send this event when it's created. 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, including a `cold` session with only outbound automated messages that nobody replied to; `session.started` is `false` for those. 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