Webhooks

Use webhooks to receive events on your server instead of polling the API.

Start at the Receive messages overview for a guided step-by-step setup.

Connect WhatsApp in the dashboard, then register HTTPS endpoints under Settings → Developer → Webhooks (or the API below). Wazapin POSTs signed JSON to your URL when subscribed events occur.

Configure endpoints

Action	Method and path
List webhook settings	`GET /v1/settings/developer/webhooks`
Create endpoint	`POST /v1/settings/developer/webhooks/endpoints`
Update endpoint	`PATCH /v1/settings/developer/webhooks/endpoints/{endpointID}`
Delete endpoint	`DELETE /v1/settings/developer/webhooks/endpoints/{endpointID}`
Rotate signing secret	`POST /v1/settings/developer/webhooks/endpoints/{endpointID}/rotate-secret`
Send test delivery	`POST /v1/settings/developer/webhooks/endpoints/{endpointID}/test`
List deliveries	`GET /v1/settings/developer/webhooks/deliveries`
Retry a delivery	`POST /v1/settings/developer/webhooks/deliveries/{messageID}/retry`

OpenAPI: API reference → Webhooks.

Delivery shape (not a single `event_type` wrapper)

Unlike some BSP docs that wrap every event as { "type": "…", "data": { } }, Wazapin deliveries follow the standard webhook signing model:

Where	What
HTTP headers	Delivery id (`svix-id` / `webhook-id`), timestamp, signature — see Webhook signature examples
JSON body	Event-specific fields only (flat object)

The event name (for example message.new) is the subscription / delivery type. It is not repeated as event_type on the body in the general case. Use the delivery id header for idempotency (same as event_id in other providers). See Message lifecycle and idempotency.

Messaging event types (common)

Subscribe to these in the app when you integrate send/receive:

Event	Fires when
`message.new`	New message in a conversation (inbound from a contact, or certain outbound echoes).
`message.sent`	Outbound message sent from your workspace.
`message.status_update`	Delivery/read/failed status changed for a sent message.
`conversation.updated`	Conversation metadata changed (assignment, status, preview, etc.).
`contact.updated`	Contact profile linked to conversations updated.
`template.status_update`	WhatsApp template approval status changed.

Full list with samples: Webhook event catalog. Filter event types per endpoint in webhook settings.

Example body: `message.new` (inbound text)

{
  "message_id": "9f1fd66d-c37a-4b50-a8c2-b4dca523f9c8",
  "conversation_id": "0f89b0f9-74b4-44f9-b9b6-48f6d4de57aa",
  "contact_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "channel_id": "wzp_abc123",
  "direction": "inbound",
  "from_phone": "6281234567890",
  "msg_type": "text"
}

Example body: `message.status_update`

{
  "message_id": "9f1fd66d-c37a-4b50-a8c2-b4dca523f9c8",
  "conversation_id": "0f89b0f9-74b4-44f9-b9b6-48f6d4de57aa",
  "status": "delivered",
  "organization_id": "org_123"
}

More samples: Webhook payload examples.

Verify signatures

Use the endpoint signing secret (whsec_…) and verify headers on the raw body before parsing JSON.

Delivery and retries

Respond with 2xx quickly; process asynchronously.
Inspect and retry failed deliveries via the deliveries API.
Deduplicate by delivery id header + message_id where applicable.

Reject requests that fail signature verification. Never verify on re-encoded JSON.

Get started

WhatsApp concepts

Send messages

Receive messages

Templates

AI & MCP

SDKs

Tools

Platform

Examples

Updates

Configure endpoints

Delivery shape (not a single `event_type` wrapper)

Messaging event types (common)

Example body: `message.new` (inbound text)

Example body: `message.status_update`

Verify signatures

Delivery and retries

​Configure endpoints

​Delivery shape (not a single event_type wrapper)

​Messaging event types (common)

​Example body: message.new (inbound text)

​Example body: message.status_update

​Verify signatures

​Delivery and retries

​Related pages

Configure endpoints

Delivery shape (not a single `event_type` wrapper)

Messaging event types (common)

Example body: `message.new` (inbound text)

Example body: `message.status_update`

Verify signatures

Delivery and retries

Related pages