Webhooks

Webhooks push signed HTTP POST requests to your server when something important happens—new messages, delivery updates, or device status changes—so you do not have to poll.

Set up a webhook

Add your URL

In the dashboard open Developers → Webhooks and add an HTTPS endpoint, or create one with the API (below).

Pick events

Subscribe only to what you handle, for example message.received and message.delivered.

Verify signatures

Check X-Wazzapi-Signature on every request before you trust the body.

Manage webhooks with the API

Action	Method	Endpoint
List	`GET`	`/api/v1/webhooks/subscriptions`
Create	`POST`	`/api/v1/webhooks/subscriptions`
Get	`GET`	`/api/v1/webhooks/subscriptions/{id}`
Update	`PATCH`	`/api/v1/webhooks/subscriptions/{id}`
Delete	`DELETE`	`/api/v1/webhooks/subscriptions/{id}`
Delivery history	`GET`	`/api/v1/webhooks/subscriptions/{id}/events`
Test endpoint	`POST`	`/api/v1/webhooks/subscriptions/{id}/ping`

Official SDKs: client.webhook_subscriptions (Python) and client.webhookSubscriptions (Node).

Security

Payloads are signed with HMAC-SHA256. Always verify against the raw body bytes, not a re-serialized JSON string. Delivery headers:

X-Wazzapi-Signature — sha256=<hex digest> of the body using your webhook secret
X-Wazzapi-Event — event name
X-Wazzapi-Event-ID — unique delivery id (use for idempotency)

Node.js

const crypto = require("crypto");

function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

Python

import hashlib
import hmac

def verify_signature(raw_body: bytes, signature: str, secret: str) -> bool:
    digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, f"sha256={digest}")

Use a constant-time comparison (as above) so timing attacks are harder.

Event	When it fires
`message.received`	Someone messaged your linked number
`message.sent`	Outbound send succeeded (worker) or WhatsApp echoed the outbound message
`message.delivered`	The recipient’s device got the message
`message.read`	The recipient opened the message
`message.failed`	Outbound send failed in the worker
`device.connected`	A device became connected
`device.disconnected`	A device dropped

Message events use the same message fields as the Inbox (text, media, quotes). Prefer data.content for the body, or data.message for the full Inbox-shaped object.

Example payload (`message.received`)

{
  "id": "97e1d724-f38d-46f6-bc4c-d9e0f4cf9285",
  "event_type": "message.received",
  "timestamp": "2026-04-26T09:15:30Z",
  "organization_id": "0f1d6e38-d6bc-49be-9c39-1fcf2f946d7e",
  "webhook_id": "a17d6351-d8f6-4cd8-ae0e-fce090afdb8f",
  "data": {
    "message_id": "f4fd147d-e2a8-4d52-9eb5-98a72f5b90ab",
    "whatsapp_message_id": "wamid.HBgMNjI4MTIzNDU2Nzg5MAUCABIYFjQ1Njc4OTA1QjQ2M0M0Q0QwAA==",
    "phone_number": "6281234567890",
    "account_name": "Support Device",
    "status": "delivered",
    "direction": "inbound",
    "message_type": "text",
    "content": "Berapa harga paket Pro?",
    "conversation_id": "3c8f1a2b-4d5e-6f70-8192-a3b4c5d6e7f8",
    "whatsapp_account_id": "c053d8ef-6c19-4ecb-9cc5-a4a64be79d92",
    "campaign_id": null,
    "batch_id": null,
    "message": {
      "id": "f4fd147d-e2a8-4d52-9eb5-98a72f5b90ab",
      "direction": "inbound",
      "content": "Berapa harga paket Pro?",
      "status": "delivered",
      "message_type": "text",
      "phone_number": "6281234567890"
    }
  }
}

See the API Reference → Webhooks for full event schemas and examples.

Retries

If your endpoint does not return 2xx within about 30 seconds, WazzAPI retries with backoff: 1 min → 5 min → 15 min → 30 min → 1 h → 2 h → 4 h → 8 h → 24 h Return quickly (accept and queue work) so deliveries succeed on the first try.

Get Started

Messaging

Connect

Campaigns

Platform

Webhooks

Webhooks

Set up a webhook

Manage webhooks with the API

Security

Example payload (`message.received`)

Retries

​Webhooks

​Set up a webhook

​Manage webhooks with the API

​Security

​Events you can subscribe to

​Example payload (message.received)

​Retries

Webhooks

Set up a webhook

Manage webhooks with the API

Security

Events you can subscribe to

Example payload (`message.received`)

Retries