# WhatsApp webhooks

Events for template and display-name reviews, number quality, account alerts, contact identity, Click-to-WhatsApp events and number provisioning.

## Events

### Account health

| Event | Description |
| --- | --- |
| [`whatsapp.account.name_status_updated`](/webhooks/whatsapp/whatsapp-account-name-status-updated) | Meta reviewed a display-name change. |
| [`whatsapp.account.quality_updated`](/webhooks/whatsapp/whatsapp-account-quality-updated) | Quality rating or messaging limit tier changed. |
| [`whatsapp.account.status_updated`](/webhooks/whatsapp/whatsapp-account-status-updated) | Meta restricted, disabled, deleted or reinstated the account. |
| [`whatsapp.account.alert_received`](/webhooks/whatsapp/whatsapp-account-alert-received) | Meta sent an account alert. |

### Templates

| Event | Description |
| --- | --- |
| [`whatsapp.template.status_updated`](/webhooks/whatsapp/whatsapp-template-status-updated) | Meta reviewed or re-reviewed a template. |
| [`whatsapp.template.category_updated`](/webhooks/whatsapp/whatsapp-template-category-updated) | Meta reclassified a template's category. |

### Contacts and events

| Event | Description |
| --- | --- |
| [`whatsapp.contact.identity_changed`](/webhooks/whatsapp/whatsapp-contact-identity-changed) | A contact changed phone number or business-scoped user id. |
| [`whatsapp.automatic_event`](/webhooks/whatsapp/whatsapp-automatic-event) | Meta detected a lead or purchase in a Click-to-WhatsApp conversation. |

### Numbers

These events follow a Zernio-provisioned number from KYC to release. The names carry a legacy `whatsapp.` prefix and fire for every provisioned number.

| Event | Description |
| --- | --- |
| [`whatsapp.number.kyc_submitted`](/webhooks/whatsapp/whatsapp-number-kyc-submitted) | A customer completed a hosted KYC link; review started. |
| [`whatsapp.number.activated`](/webhooks/whatsapp/whatsapp-number-activated) | A provisioned number is ready to connect. |
| [`whatsapp.number.declined`](/webhooks/whatsapp/whatsapp-number-declined) | A regulated number order was declined in review. |
| [`whatsapp.number.action_required`](/webhooks/whatsapp/whatsapp-number-action-required) | The regulator asked for more information on an order. |
| [`whatsapp.number.verification_required`](/webhooks/whatsapp/whatsapp-number-verification-required) | A number needs end-user ID verification. |
| [`whatsapp.number.suspended`](/webhooks/whatsapp/whatsapp-number-suspended) | An active number was suspended. |
| [`whatsapp.number.reactivated`](/webhooks/whatsapp/whatsapp-number-reactivated) | A suspended number is usable again. |
| [`whatsapp.number.released`](/webhooks/whatsapp/whatsapp-number-released) | A number was released (terminal). |

## How it behaves

Number events follow this lifecycle. Labels drop the `whatsapp.number.` prefix.

<Mermaid
  chart={`stateDiagram-v2
  direction LR
  [*] --> pending_regulatory: kyc_submitted
  pending_regulatory --> active: activated
  pending_regulatory --> regulatory_declined: declined
  regulatory_declined --> pending_regulatory: remediate (API call)
  active --> suspended: suspended
  suspended --> active: reactivated
  active --> released: released
  suspended --> released: released
  released --> [*]`}
/>

<Accordions>
<Accordion title="Zernio forwards Meta's review outcomes as they land" id="zernio-forwards-metas-review-outcomes-as-they-land">

Zernio forwards Meta's WhatsApp Business Account fields as events: template status and category changes, and display-name review outcomes. Rules per event are on each event page.

</Accordion>
<Accordion title="Category changes arrive twice" id="category-changes-arrive-twice">

`whatsapp.template.category_updated` is sent as a 24-hour advance notice (`scheduled`) and again when the change is `applied`. See the event page.

</Accordion>
<Accordion title="Health events fire on change, per number" id="health-events-fire-on-change-per-number">

Health events fire on change only. Meta events that apply to the whole WhatsApp Business Account (restrictions, business-level alerts, portfolio-wide tier changes) fire once per connected number on it.

</Accordion>
<Accordion title="Identity changes carry old and new identifiers" id="identity-changes-carry-old-and-new-identifiers">

Zernio moves the inbox conversation and the contact before the event arrives. Use `previous` and `current` to re-key your own records. See the event page.

</Accordion>
<Accordion title="Automatic events carry the Conversions API match key" id="automatic-events-carry-the-conversions-api-match-key">

Zernio delivers `ctwaClid` on `whatsapp.automatic_event` and writes it onto the conversation. Availability and opt-in rules are on the event page.

</Accordion>
<Accordion title="Number events fire on status transitions" id="number-events-fire-on-status-transitions">

Every number has a `status`, readable with [Get phone number](/phone-numbers/get-phone-number). Zernio fires an event on each transition.

Polling can also catch short-lived statuses the events skip: `pending_payment`, `provisioning`, `verifying` (not billed until `active`) and `releasing`.

</Accordion>
<Accordion title="Instant numbers skip the review states" id="instant-numbers-skip-the-review-states">

A number in an [instant-provisioning country](/platforms/phone-numbers/availability) goes straight to `active`, so the first event is `whatsapp.number.activated`. Review states apply only to regulated (KYC) countries.

</Accordion>
<Accordion title="`kyc_submitted` fires only for hosted share links" id="kyc_submitted-fires-only-for-hosted-share-links">

Only a [white-labeled KYC form](/platforms/phone-numbers/kyc#hand-the-form-off-white-label) fires it. See the event page.

</Accordion>
<Accordion title="`action_required` and `verification_required` leave the status unchanged" id="action_required-and-verification_required-leave-the-status-unchanged">

Zernio keeps the number at `pending_regulatory` while the regulator waits on you. These events say the review is blocked, not that the state changed.

</Accordion>
<Accordion title="`regulatory_declined` can be remediated" id="regulatory_declined-can-be-remediated">

[Resubmit corrected details](/phone-numbers/remediate-phone-number) and the number returns to `pending_regulatory`. Same number, no new billing.

</Accordion>
<Accordion title="`released` is the only terminal state" id="released-is-the-only-terminal-state">

Zernio recovers `suspended` numbers with `reactivated`. A suspension left unresolved ends in release.

</Accordion>
</Accordions>

## Related

- [Webhooks](/webhooks): create an endpoint, retries, signatures.
- [WhatsApp templates](/platforms/whatsapp/templates): create the templates these reviews are about.
- [Click-to-WhatsApp](/platforms/whatsapp/ctwa): ads and conversions.
- [Inbox webhooks](/webhooks/inbox): the messages themselves.
- [Phone numbers](/platforms/phone-numbers): purchase, KYC and availability.
- [Get phone number](/phone-numbers/get-phone-number): read `status` on demand.
- [Remediate a number](/phone-numbers/remediate-phone-number): fix a declined order.