Account webhooks
Events fired when social accounts are connected or disconnected.
Events for connected social account lifecycle. Delivery, retries, idempotency, and signature verification work the same for every event and are covered in the webhooks overview.
Events
| Event | Description |
|---|---|
account.connected | Fired when a social account is successfully connected. |
account.disconnected | Fired when a connected social account becomes disconnected. |
account.connected
Fired when a social account is successfully connected. Subscribe with Create webhook settings or Update webhook settings.
Stable webhook event ID
"account.connected"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.
date-timeResponse Body
account.disconnected
Fired when a connected social account becomes disconnected. Subscribe with Create webhook settings or Update webhook settings.
Stable webhook event ID
"account.disconnected"UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.
date-timeResponse Body
How disconnect detection works
account.disconnected reaches you through two paths, and which one fires determines how quickly you hear about it.
- API-initiated removals (for example
DELETE /v1/accounts/{id}) emit immediately, withdisconnectionType: "intentional". - A phone-side WhatsApp disconnect (WhatsApp Business app > Settings > Account > Business Platform > Disconnect) emits within seconds of Meta notifying us, with
disconnectionType: "unintentional". Thereasoncarries Meta's own explanation where Meta provides one, which distinguishes a deliberate disconnect (BUSINESS_DOWNGRADE,CHANGE_NUMBER,USER_RE_REGISTERED) from Meta dropping an idle number (PRIMARY_INACTIVITYafter about 14 days,COMPANION_INACTIVITYafter about 30), along with whether the user or Meta initiated it. - Everything else (a number deleted in WhatsApp Manager, a revoked grant, a channel Meta silently stops serving) is caught by a periodic reconciliation against Meta rather than a notification. That path is deliberately conservative: it confirms across more than one probe before acting, so it can lag by anywhere from minutes to about a day.
Known limitations
- Meta's notifications are best-effort, so a disconnect can still fall through to the slower reconciliation path above.
- Do not treat the absence of this event as proof a channel is alive. For WhatsApp, poll the liveness check (
GET /v1/whatsapp/number-info) or the account health endpoint, which includes a live Meta link probe for WhatsApp accounts.