Introduction

Use webhooks to receive the events currently available for your workspace. Subscribe only to event types returned for that account; a tool or channel visible elsewhere does not guarantee that every event is available here.

1. Discover supported events

Call GET /api/ext/v3/webhooks/event-types. Select the event types needed for incoming messages and supported message-status changes. 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.