Phone number webhooks

Lifecycle events for phone numbers provisioned through Zernio: KYC submission, regulatory review outcomes, activation, suspension, and release. The event names carry a whatsapp. prefix for legacy reasons, but they fire for every provisioned number. Delivery, retries, idempotency, and signature verification work the same for every event and are covered in the webhooks overview.

Events

How events map to number status

Every number carries a status you can read back with Get phone number. The events fire on its transitions — diagram labels drop the whatsapp.number. prefix:

• Instant numbers skip the left half. A number in an instant-provisioning country goes straight to active, so the first event you see is whatsapp.number.activated. The review states only apply to regulated (KYC) countries.
• kyc_submitted fires only for hosted share links. When you submit KYC directly over the API you already know the moment of submission; the event exists so a white-labeled KYC form can notify you when your customer finishes it.
• action_required and verification_required are not statuses. The number stays pending_regulatory while the regulator waits on you; these events tell you review is blocked, not that the state changed.
• regulatory_declined is not terminal. Resubmit corrected details and the number returns to pending_regulatory — same number, no new billing. You are never billed for a number that was declined.
• released is the only terminal state. suspended numbers recover via reactivated, but a suspension left unresolved ends in release.
• Polling can also catch short-lived transit statuses the events skip over: pending_payment, provisioning, verifying (provisioned, awaiting confirmation — not billed until active), and releasing.

---

whatsapp.number.kyc_submitted

Fired when an end customer completes a hosted KYC share link. The number enters regulatory review (pending_regulatory) under your account; whatsapp.number.activated or whatsapp.number.declined follows once the provider rules on it. Use it to update your own UI the moment the customer finishes the form, instead of polling. Subscribe with Create webhook settings or Update webhook settings.

---

whatsapp.number.activated

Fired when a WhatsApp number you provisioned through Zernio finishes setup and is ready to connect. For regulated (non-US) numbers this can take 1-3 business days after the order is approved, so the webhook saves you from polling. Subscribe with Create webhook settings or Update webhook settings.

---

whatsapp.number.declined

Fired when a regulated number order is declined during regulatory review and no number is activated. The order never activates and you are never billed for it. Subscribe with Create webhook settings or Update webhook settings.

---

whatsapp.number.action_required

Fired when the regulator reviewing an already-placed number order asks for more information (for example, a certificate of company incorporation). Nothing was rejected: the order stays pending, but it will not progress until the information is provided. reason carries the regulator's request verbatim when available. Provide the missing details from the dashboard's phone-numbers page, or re-submit the relevant fields via the remediation endpoint; the review resumes automatically. Subscribe with Create webhook settings or Update webhook settings.

---

whatsapp.number.verification_required

Fired when a regulated number requires the end user to complete an identity check (for example, Australian mobile numbers). The payload carries a one-time verificationUrl to forward to the person whose ID is on file; the order completes once they pass. Subscribe with Create webhook settings or Update webhook settings.

---

whatsapp.number.suspended

Fired when an active number is suspended, for example after a failed payment. The number stops working until the issue is resolved, after which a whatsapp.number.reactivated event is sent. The payload carries a reason (such as payment_failed or subscription_ended). Subscribe with Create webhook settings or Update webhook settings.

---

whatsapp.number.reactivated

Fired when a suspended number is reactivated (for example, the payment recovered) and is usable again. Subscribe with Create webhook settings or Update webhook settings.

---

whatsapp.number.released

Fired when a number is released and is no longer usable, whether you released it, a billing cleanup released it, or an admin did. This is terminal. The payload carries a reason (such as user_requested or cleanup_suspended). Subscribe with Create webhook settings or Update webhook settings.