Skip to content
Wazapin
Esc
↑↓navigate↵open⌘Jpreview
On this page

Receive messages & webhooks

Configure HTTPS endpoints to receive real-time messages, delivery receipts, and template status updates from Wazapin.

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.
  2. An active API Key: For managing webhook settings programmatically (if needed). See API keys.
  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 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.

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.

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
message.new (msg_type: image, video, audio, document, sticker) User sent a photo, voice note, document, etc. Handle inbound media
message.new (msg_type: interactive) User replied to a quick-reply button or list menu. Handle interactive replies
message.status_update A message transitioned to sent, delivered, read, or failed. Handle delivery status

For a complete list of subscribable events, see the 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.

Step 6: Next steps

Was this page helpful?