Webhooks

Receive real-time events — inbound messages, delivery receipts, and status changes — via signed payloads to your endpoint.

Event Types

Event	Description
message.received	Incoming message from end-user
message.status	Delivery status (sent/delivered/read/failed)
message.reaction	Emoji reaction to a message

Payload Format

JSON

{
  "event": "message.received",
  "timestamp": "2026-03-05T12:00:00Z",
  "client_ref": "partner-123",
  "phone_number": "+1234567890",
  "from": "+0987654321",
  "message": {
    "id": "wamid.xxx",
    "type": "text",
    "text": { "body": "Hello!" },
    "timestamp": "1709640000"
  },
  "contact": {
    "name": "John Doe",
    "wa_id": "0987654321"
  }
}

Signature Verification

Every webhook includes an X-Intelli-Signature header containing an HMAC-SHA256 signature of the request body.

Node.js

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
      .update(body)
      .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Python

import hmac, hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Retry Policy

If your endpoint returns a non-2xx status or times out:

Attempt 1: Immediate
Attempt 2: After 10 seconds
Attempt 3: After 60 seconds
Attempt 4: After 300 seconds (5 min)

After all retries fail, the delivery is marked as failed. You can view failed deliveries in the webhook logs.

Docs/Webhooks