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`	WhatsApp accepted your outbound message
`message.delivered`	The recipient’s device got the message
`message.read`	The recipient opened the message
`message.failed`	Outbound send failed
`device.connected`	A device is healthy again
`device.disconnected`	A device dropped or needs attention

Example payload

{
  "id": "0b97762a-b93e-4b32-9441-3c99ba4cc0ff",
  "event_type": "message.delivered",
  "timestamp": "2026-04-26T10:20:22Z",
  "organization_id": "0f1d6e38-d6bc-49be-9c39-1fcf2f946d7e",
  "webhook_id": "a17d6351-d8f6-4cd8-ae0e-fce090afdb8f",
  "data": {
    "message_id": "8806d2db-61c7-4dd3-804e-4e90b65876d2",
    "status": "delivered",
    "phone_number": "6281234567890",
    "whatsapp_account_id": "c053d8ef-6c19-4ecb-9cc5-a4a64be79d92"
  }
}

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.

​Webhooks

​Set up a webhook

​Manage webhooks with the API

​Security

​Events you can subscribe to

​Example payload

​Retries

Webhooks

Set up a webhook

Manage webhooks with the API

Security

Events you can subscribe to

Example payload

Retries