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

---

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.