Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wazzapi.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Webhooks

Webhooks let WazzAPI send signed HTTP POST requests to your endpoint whenever important events happen.

​
Overview

Instead of polling for updates, register a webhook subscription and let WazzAPI notify your application automatically.
1

Configure Webhook URL

Go to Developers > Webhooks in the dashboard and add your endpoint URL.
2

Choose events

Subscribe to the events your application actually handles, such as message.delivered or device.disconnected.
3

Receive signed payloads

Start receiving events such as message.received, message.delivered, device.connected, and device.disconnected.

​
Security

All webhook payloads are signed with HMAC-SHA256. Verify the signature against the raw request body bytes before parsing JSON.

​
Verifying Signatures

WazzAPI includes these headers on each delivery:
  • X-Wazzapi-Signature
  • X-Wazzapi-Event
  • X-Wazzapi-Event-ID
The signature header contains a sha256= prefixed digest of the raw body signed with your webhook secret.
Node.js Example
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}`)
  );
}
Always use a constant-time comparison function to prevent timing attacks.

​
Event Types

Common events you can subscribe to:
EventDescription
message.receivedAn inbound WhatsApp message arrived.
message.sentAn outbound message was accepted by WhatsApp.
message.deliveredAn outbound message reached the recipient device.
message.readThe recipient read the outbound message.
message.failedAn outbound message failed with a reason.
device.connectedA linked WhatsApp device returned to a healthy state.
device.disconnectedA linked device lost connectivity or needs attention.

​
Payload Structure

{
  "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"
  }
}

​
Retry Policy

If your endpoint does not return a 2xx response in time, WazzAPI retries with backoff. Current retry intervals are:
  • 1 minute
  • 5 minutes
  • 15 minutes
  • 30 minutes
  • 1 hour
  • 2 hours
  • 4 hours
  • 8 hours
  • 24 hours
Keep your webhook endpoint fast and reliable. If you need to do heavier processing, queue the work and return 200 OK immediately.