Events
Your backend hears when a number drops, gets blocked or comes back, without polling.
Set an events URL in Dashboard → Developers or with the endpoint below; you get a signing secret once. We POST JSON to it, one event per request, and retry with backoff for about a day on any non-2xx, so make the handler idempotent on id. Events carry status only, never message content. New events are added over time: ignore names you do not handle.
The payload
POST <your events URL>
X-EC-Event: connection.disconnected
X-EC-Delivery: <delivery id>
X-EC-Signature: t=1761900000,v1=<hex>
{
"id": "<delivery id>",
"event": "connection.disconnected",
"occurred_at": "…",
"connection": { "id": "…", "external_ref": null, "phone": "…", "status": "disconnected", "token_ready": true, "sending_health": "AVAILABLE", "waba_id": "…", "phone_number_id": "…" },
"reason": "PRIMARY_INACTIVITY"
}v1 = HMAC-SHA256(secret, "<t>.<raw body>"). Verify on the raw body, reject a stale t (over 5 minutes), compare in constant time, and deduplicate on id.
The events
connection.connected: A number connected, with its token.connection.disconnected:reasonis Meta's code when known;PRIMARY_INACTIVITYis the 14-day rule, reconnectable;ACCOUNT_DISCONNECTEDmeans the number's owner removed us.connection.removed: Removed from the account.connection.suspended: Your subscription lapsed.connection.token_missing: Meta finished without issuing the number's own token; a reconnection fixes it.connection.sending_blocked: Meta stopped delivering the messages the business starts;block_codesays why.connection.sending_restored: Sending works again.channel.connected,channel.disconnected,channel.removed,channel.suspended: The same for a channel, with achannelobject (the Get a channel view) instead ofconnection.post.published,post.failed: With the post and its channel.automation.run_failed: The run id, the failed step and why. Never what anyone wrote, and never a collected number: fetch the run for details.automation.broken: An AI key was refused, so the automations using it stopped until a key is saved again.test: Sent by Send a test event.
Read the events URL
GET/api/v1/events-endpoint
Where this account's events go, and which events it can receive.
Response 200
{
"url": "https://hooks.example.com/ec-events",
"events": [
"connection.connected",
"connection.disconnected",
"…"
]
}Set the events URL
PUT/api/v1/events-endpoint
Sets it and answers the signing secret, once. When a URL is already set, a new one needs replace_secret: true, because it issues a new secret and your endpoint rejects every event until it has it.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
urlrequired | body | https URL or null | null turns events off. |
replace_secret | body | true | Needed to change a URL that is already set. |
Request
{
"url": "https://hooks.example.com/ec-events"
}Response 200
{
"url": "https://hooks.example.com/ec-events",
"signing_secret": "whsec_…",
"events": [
"connection.connected",
"…"
]
}Errors besides the common ones: secret_change.
Send a test event
POST/api/v1/events-endpoint/test
Queues a test event to the events URL, signed and retried like every other, so you can check your handler before anything real happens. Answers the delivery id, which is also the id in the payload.
Response 202
{
"id": "<delivery id>",
"event": "test"
}Errors besides the common ones: invalid_request.