Skip to main content
POST

Authorizations

Authorization
string
header
required

An API key of one app, sent as Authorization: Bearer <key>. Keys start with fk_test_ (test mode: sandbox senders and test data only) or fk_live_ (live mode). Keep live keys on your server; never ship them in an app or page.

Headers

Idempotency-Key
string

A unique string (up to 255 characters) that makes this request safe to retry. A repeat with the same key within 24 hours returns the first answer instead of acting again. See "Idempotency" in the introduction.

Required string length: 1 - 255
Flow-Version
string<date>

The API version to use, as a date. Without it, the version pinned to your app when it was created is used.

Example:

"2026-11-01"

Path Parameters

webhook_endpoint_id
string
required

The webhook endpoint's ID. A webhook endpoint ID, we_ and a ULID.

Pattern: ^we_[0-9A-HJKMNP-TV-Z]{26}$
Example:

"we_01JB8ZF6P8R0T2W4Y6A8C0E2F4"

Body

application/json

Options for rotating a webhook endpoint's signing secret.

overlap_seconds
integer
default:86400

How long the previous secret keeps signing alongside the new one, in seconds (at most 7 days). 0 retires it at once.

Required range: 0 <= x <= 604800

Response

The secret was rotated. secret is the new secret, included this once; previous_secret_expires_at says when the old one stops signing.

A URL that receives your app's events of the types it subscribes to.

id
string
required

A webhook endpoint ID, we_ and a ULID.

Pattern: ^we_[0-9A-HJKMNP-TV-Z]{26}$
Example:

"we_01JB8ZF6P8R0T2W4Y6A8C0E2F4"

url
string<uri>
required

The HTTPS URL events are posted to.

events
enum<string>[]
required

The event types delivered to this endpoint.

  • message.received: the contact sent a message (data.message.content, with kind: basic, voice, button_reply for a tap on a button or list row, reaction, location, contact_card or file_blocked).
  • message.sent, message.delivered, message.read, message.failed: the status of your outbound messages. message.failed carries the error in data.message.error.
  • reaction.added, reaction.removed: the contact reacted to a message.
  • typing.started, typing.stopped: the contact is typing, where the channel reports it.
  • conversation.started: the first inbound message from a new contact, a sandbox join (via sandbox_join: Flow itself confirms the join, then the join message reaches you as the contact's first message.received), or your first send to a new contact (via outbound).
  • conversation.window_closing: WhatsApp only, opt-in. The 24-hour window closes in 1 hour.
  • sender.status_changed: a sender was throttled, flagged, banned or restored, or its WhatsApp quality rating changed.
  • template.status_changed: Meta approved, rejected or paused a template.
  • contact.deleted: a contact was deleted with DELETE /v0/contacts/{contact_id}. Carries only the contact's ID; delete what you keep about them too.
  • contact.left: a person on a shared sender (the sandbox) joined another app, or the other mode of your app, by sending its join message. Nothing more reaches you from them, and sends to them fail with sandbox_contact_left, until they send your join message again.
  • call.received: iMessage only. A contact tried to FaceTime the line. The line cannot answer it, and the call does not count as the contact writing: a reply-only line can message them only after they write.
Available options:
message.received,
message.sent,
message.delivered,
message.read,
message.failed,
reaction.added,
reaction.removed,
typing.started,
typing.stopped,
conversation.started,
conversation.window_closing,
sender.status_changed,
template.status_changed,
contact.deleted,
contact.left,
call.received
enabled
boolean
required

Whether events are delivered. Disabled endpoints keep their place; nothing is lost from the log.

livemode
boolean
required

Whether the endpoint receives live-mode or test-mode events.

created_at
string<date-time>
required

When the endpoint was created.

description
string

Your note about the endpoint.

secret
string

The signing secret (whsec_...). Only in the answers to create and to rotate the secret.

previous_secret_expires_at
string<date-time>

While a secret rotation overlaps, when the previous secret stops signing. Absent when only one secret is active.