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:
ActionMethod and pathDescription
Create endpointPOST /v1/settings/developer/webhooks/endpointsRegister a new webhook listener URL.
List settingsGET /v1/settings/developer/webhooksList registered endpoints and active subscriptions.
Update endpointPATCH /v1/settings/developer/webhooks/endpoints/{endpointID}Edit URL or subscribed event types.
Delete endpointDELETE /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 typeDescriptionTask 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_updateA 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