---
title: "Receive messages & webhooks"
description: "Configure HTTPS endpoints to receive real-time messages, delivery receipts, and template status updates from Wazapin."
---

> 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.

# Receive messages & webhooks

Wazapin uses webhooks to push events (such as customer replies or delivery receipts) to your server in real time. Instead of polling the API, configure your server to listen for signed HTTP POST requests.

> Fetch the complete documentation index at: https://docs.wazapin.id/llms.txt

Follow this step-by-step guide to receive your first WhatsApp webhook event.

---

### Step 1: Prerequisites

Before receiving events, ensure you have:
1. **A connected WhatsApp number:** Either an official WABA or unofficial channel. See [Connect your number](/getting-started/connect-channel).
2. **An active API Key:** For managing webhook settings programmatically (if needed). See [API keys](/api/authentication).
3. **An HTTPS endpoint:** A publicly accessible URL on your server that can receive HTTP `POST` requests. For local development, use tools like Ngrok or Localtunnel to expose your local port.

---

### Step 2: Configure your webhook endpoint

You can configure endpoints through the [Wazapin Dashboard](https://app.wazapin.com) under **Settings → Developer → Webhooks**, or programmatically using the API:

| Action | Method and path | Description |
| :--- | :--- | :--- |
| **Create endpoint** | `POST /v1/settings/developer/webhooks/endpoints` | Register a new webhook listener URL. |
| **List settings** | `GET /v1/settings/developer/webhooks` | List registered endpoints and active subscriptions. |
| **Update endpoint** | `PATCH /v1/settings/developer/webhooks/endpoints/{endpointID}` | Edit URL or subscribed event types. |
| **Delete endpoint** | `DELETE /v1/settings/developer/webhooks/endpoints/{endpointID}` | Remove an endpoint. |

For the complete OpenAPI reference on these endpoints, see [Webhooks API reference](/api-reference).

---

### Step 3: Verify signatures

Every webhook delivery is signed using an **endpoint signing secret** (formatted as `whsec_...`). To protect your server from unauthorized requests, you must verify the signature headers before parsing the JSON body.

Look for the following headers on each delivery:
- `svix-id` or `webhook-id`
- `svix-timestamp` or `webhook-timestamp`
- `svix-signature` or `webhook-signature`

For manual signature verification and SDK helpers (Node/Express, Python), see the [Webhook signature verification guide](/api/webhook-signature-examples).

---

### Step 4: Route by event type

Once verified, check the event type of the delivery. Subscribed events are delivered as flat JSON objects. Route them in your application logic based on the `msg_type` or event name:

| Event type | Description | Task guide |
| :--- | :--- | :--- |
| **`message.new`** (msg_type: `text`) | User sent a text reply. | [Handle inbound text](/guides/handle-inbound-text) |
| **`message.new`** (msg_type: `image`, `video`, `audio`, `document`, `sticker`) | User sent a photo, voice note, document, etc. | [Handle inbound media](/guides/handle-inbound-media) |
| **`message.new`** (msg_type: `interactive`) | User replied to a quick-reply button or list menu. | [Handle interactive replies](/guides/handle-interactive-replies) |
| **`message.status_update`** | A message transitioned to `sent`, `delivered`, `read`, or `failed`. | [Handle delivery status](/guides/handle-delivery-status) |

For a complete list of subscribable events, see the [Webhook event catalog](/api/webhook-event-catalog).

---

### Step 5: Handle idempotency

Network retries can cause your server to receive the same webhook event more than once. 

* Extract the `svix-id` (or `webhook-id`) header from the request.
* Store processed event IDs in your database or cache (e.g., Redis).
* If a request arrives with an ID you have already processed, return a `200 OK` response immediately and skip processing.

For detailed design patterns, see [Message lifecycle and idempotency](/api/message-lifecycle-idempotency).

---

### Step 6: Next steps

* View sample JSON payloads for every event type in [Webhook payload examples](/api/inbound-webhook-examples).
* Implement a robust, production-ready webhook receiver using the [Example: handle webhook events](/recipes/handle-webhook-events) recipe.

Source: https://docs.wazapin.id/receive-messages/overview/index.mdx