Skip to main content

​
Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your WazzAPI account, such as message delivery updates or incoming messages.

​
Overview

Instead of polling the API, configure a webhook URL to have WazzAPI push data to your server immediately.
1

Configure Webhook URL

Go to Settings > Webhooks in your Dashboard and enter your endpoint URL.
2

Verify Ownership

WazzAPI will send a test POST request. Your endpoint must return 200 OK.
3

Receive Events

Start listening for events like message.received and message.delivered.

​
Security

All webhook payloads are signed with HMAC-SHA256 to ensure authenticity. You should verify this signature before processing any data.

​
Verifying Signatures

The signature is sent in the X-Webhook-Signature header. It is a hex digest of the request body (raw bytes) signed with your Webhook Secret.
Node.js Example
const crypto = require('crypto');

function verifySignature(req, secret) {
  const signature = req.headers['x-webhook-signature'];
  const body = JSON.stringify(req.body); // Use raw body if available

  const hash = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return signature === `sha256=${hash}`;
}
Always use a constant-time comparison function to prevent timing attacks.

​
Event Types

Common events you can subscribe to:
EventDescription
message.sentMessage successfully sent to WhatsApp server.
message.deliveredMessage delivered to the recipient’s device.
message.readRecipient read the message (blue ticks).
message.failedMessage failed to send (check payload for reason).
session.connectedWhatsApp instance connected successfully.
session.disconnectedWhatsApp instance disconnected (e.g. phone offline).

​
Payload Structure

{
  "id": "evt_123456",
  "event": "message.delivered",
  "organizationId": "org_abc123",
  "timestamp": "2023-10-01T12:00:00Z",
  "data": {
    "messageId": "msg_7890",
    "status": "delivered",
    "recipient": "+1234567890"
  }
}

​
Retry Policy

If your server fails to respond with a 2xx status code, WazzAPI will retry:
  • Interval: Exponential backoff (1m, 2m, 4m, etc.)
  • Max Retries: 5 attempts
Ensure your webhook endpoint is fast and reliable. For heavy processing, offload work to a background queue and return 200 OK immediately.