Webhooks

Receive Wazapin events on your HTTPS endpoint using the developer webhooks API.

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

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.