Introduction

Use the documented webhook events for your account and channel. The event-types API lists registered names; a returned name alone does not establish that the event is currently deliverable for your account. Check its event reference and product availability, then verify an actual permitted event reaches your enabled subscription before relying on it.

1. Discover registered events

Call GET /api/ext/v3/webhooks/event-types. Select documented event types needed for incoming messages and supported message-status changes; do not assume every registered name has a supported delivery path. Refer to each event's payload documentation for its identifier fields; event shapes are not interchangeable.

2. Create and enable the subscription — V2 exception

Webhook creation currently uses POST /{tenantId}/api/v2/webhookEndpoints. The body is an array. phoneNumber is your sending WhatsApp channel number, not a customer number or arbitrary channel ID. This creation path does not imply support for every social channel.

[
  {
    "phoneNumber": "15551234567",
    "url": "https://example.com/wati/webhook",
    "status": 1,
    "eventTypes": ["message"]
  }
]

Replace the sample phone/URL and select actual event names from step 1 (message is illustrative; use it only if returned). Numeric V2 status is 0 Disabled, 1 Enabled, 2 Defective. Send 1 to enable. Check ok and save the returned subscription ID; do not assume HTTP success means subscription creation succeeded. Creating the same URL again may be rejected, so list subscriptions before repeating an uncertain create.

3. Manage the saved subscription in V3

Use the V3 subscription list to find and inspect the subscription. Its returned ID is used for GET, PUT and DELETE /api/ext/v3/webhooks/{id}.

Before PUT, read the current subscription and retain its url: every update requires a non-empty URL, even when only changing events or status. V3 status values are strings, such as Enabled, rather than the V2 creation numbers.

4. Receive, acknowledge and correlate

Accept the callback on your HTTPS endpoint. Return a 2xx after safely accepting it for processing; business processing can run asynchronously.
Deduplicate repeat deliveries before applying side effects. Use the documented event/message identifiers and status for that event family; do not assume every payload includes a universal event ID.
Do not depend on delivery order. Reconcile state using the message identifiers, status and timestamps supplied by the relevant event; a late callback must not make a delivered message appear pending again.
Match incoming status callbacks with IDs retained from the send and the applicable event contract. Message acceptance, delivery and read status are distinct. A missing callback does not establish that no send occurred.
Treat contact IDs, conversation IDs, channel numbers and BSUIDs as different identifiers. See BSUID & Target Format; do not require a phone field for every supported BSUID payload.

Non-2xx responses and delivery errors can cause retries. Retry counts/intervals and subscription failure handling depend on the service configuration; this guide does not promise a universal retry count, interval, signature or replay API. Inspect the subscription's current status and restore it through supported management when it is disabled or defective.

You can also configure a subscription through the WATI Webhooks UI. A sample callback checks endpoint connectivity; verify your selected event types with an actual permitted event before relying on the integration.

Additional event references

The event names phoneNumberQualityUpdated and accountReviewUpdated are case-sensitive. Legacy and V2 sent/delivered/read/replied notifications share their event reference pages; inspect eventType before requiring V2-only correlation fields.

Migrating an existing integration

Webhook access is available on every plan, subject to applicable volume limits; specific events also require the relevant product/channel and a supported delivery path. Follow the webhook migration checklist before changing subscriptions or parsers. In particular, V3 PUT uses eventTypes, while V3 responses use event_types.