---
title: "Webhooks"
description: "Receive Wazapin events on your HTTPS endpoint using the developer webhooks API."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.wazapin.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

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

:::note
Start at the [Receive messages overview](/receive-messages/overview) for a guided step-by-step setup.
:::

Connect WhatsApp in the [dashboard](https://app.wazapin.com), then register HTTPS endpoints under **Settings → Developer → Webhooks** (or the API below). Wazapin **POST**s 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](/api/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](/api/message-lifecycle-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](/api/webhook-event-catalog). Filter event types per endpoint in webhook settings.

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

```json
{
  "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`

```json
{
  "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](/api/inbound-webhook-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.

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

## Related pages

- [Webhook payload examples](/api/inbound-webhook-examples)
- [Webhook signature examples](/api/webhook-signature-examples)
- [Message lifecycle and idempotency](/api/message-lifecycle-idempotency)
- [Example: handle webhook events](/recipes/handle-webhook-events)

## List webhook endpoints

## Create webhook endpoint

Source: https://docs.wazapin.id/api/webhooks/index.mdx