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

ActionMethod and path
List webhook settingsGET /v1/settings/developer/webhooks
Create endpointPOST /v1/settings/developer/webhooks/endpoints
Update endpointPATCH /v1/settings/developer/webhooks/endpoints/{endpointID}
Delete endpointDELETE /v1/settings/developer/webhooks/endpoints/{endpointID}
Rotate signing secretPOST /v1/settings/developer/webhooks/endpoints/{endpointID}/rotate-secret
Send test deliveryPOST /v1/settings/developer/webhooks/endpoints/{endpointID}/test
List deliveriesGET /v1/settings/developer/webhooks/deliveries
Retry a deliveryPOST /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:
WhereWhat
HTTP headersDelivery id (svix-id / webhook-id), timestamp, signature — see Webhook signature examples
JSON bodyEvent-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:
EventFires when
message.newNew message in a conversation (inbound from a contact, or certain outbound echoes).
message.sentOutbound message sent from your workspace.
message.status_updateDelivery/read/failed status changed for a sent message.
conversation.updatedConversation metadata changed (assignment, status, preview, etc.).
contact.updatedContact profile linked to conversations updated.
template.status_updateWhatsApp 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.