Webhooks

Subscribing

POST a public https URL and the event names to /webhooks. The response includes signing_secret once; store it. Available events: message.received, message.status, template.status, broadcast.completed, contact.opted_out, conversation.status_changed, lead.created. A subscription that fails repeatedly is switched to disabled; enable it again with a PUT.

What we send

A POST with a JSON body { id, event, createdAt, data } and these headers:

• x-edwyz-event: the event name.
• x-edwyz-delivery: delivery id, the same across retries.
• x-edwyz-timestamp: seconds since the epoch when this attempt was signed.
• x-edwyz-signature: sha256= followed by the hex HMAC-SHA256 of the timestamp, a dot, and the exact raw body, keyed with your secret.

Answer with any 2xx status within 10 seconds. Redirects are not followed. Failed deliveries are retried, so deduplicate on the id in the body.

Events

The dataobject of each event is shown below. Fields that can be missing are null, never absent. A person who messages you through a WhatsApp username has no phone number: use the contact's bsuid to recognise them.

{
  "conversationId": "ckconv1",
  "channel": "109876543210987",
  "assignedTo": null,
  "contact": {
    "id": "ckcontact1",
    "phone": "+919876543210",
    "bsuid": "IN.13491208655302741918",
    "waId": "919876543210",
    "username": null,
    "name": "Asha"
  },
  "message": {
    "id": "wamid.HBgM...",
    "type": "text",
    "text": "Hi, is the red one in stock?",
    "mediaId": null,
    "mimeType": null,
    "timestamp": "2026-10-27T10:15:00.000Z"
  },
  "referral": {
    "sourceType": "ad",
    "sourceId": "120210000000000",
    "sourceUrl": "https://fb.me/example",
    "headline": "Spring sale",
    "ctwaClid": "ARAk..."
  }
}

{
  "messageId": "ckmsg1",
  "conversationId": "ckconv1",
  "wamid": "wamid.HBgM...",
  "status": "delivered",
  "errorCode": null,
  "timestamp": "2026-10-27T10:15:00.000Z",
  "contact": {
    "id": "ckcontact1",
    "phone": "+919876543210",
    "bsuid": "IN.13491208655302741918",
    "waId": "919876543210",
    "username": null,
    "name": "Asha"
  }
}

{
  "templateId": "cktemplate1",
  "name": "order_update",
  "language": "en",
  "category": "utility",
  "status": "approved",
  "reason": null,
  "timestamp": "2026-10-27T10:15:00.000Z"
}

{
  "broadcastId": "ckbroadcast1",
  "name": "October offer",
  "templateId": "cktemplate1",
  "completedAt": "2026-10-27T10:15:00.000Z",
  "totals": {
    "total": 120,
    "sent": 118,
    "delivered": 110,
    "read": 64,
    "failed": 2,
    "skipped": 0
  }
}

{
  "contact": {
    "id": "ckcontact1",
    "phone": "+919876543210",
    "bsuid": "IN.13491208655302741918",
    "waId": "919876543210",
    "username": null,
    "name": "Asha"
  },
  "contactId": "ckcontact1",
  "phone": "+919876543210",
  "optedOutAt": "2026-10-27T10:15:00.000Z",
  "source": "stop_keyword"
}

{
  "conversationId": "ckconv1",
  "contactId": "ckcontact1",
  "from": "open",
  "to": "solved",
  "changedBy": "ckuser1",
  "source": "user",
  "timestamp": "2026-10-27T10:15:00.000Z"
}

{
  "leadId": "cklead1",
  "status": "new",
  "source": "meta_lead_form",
  "formId": "5550001112223",
  "campaignId": "120210000000001",
  "adId": "120210000000002",
  "createdAt": "2026-10-27T10:15:00.000Z",
  "contact": {
    "id": "ckcontact1",
    "phone": "+919876543210",
    "bsuid": "IN.13491208655302741918",
    "waId": "919876543210",
    "username": null,
    "name": "Asha"
  },
  "fields": {
    "full_name": "Asha",
    "phone_number": "+919876543210",
    "city": "Pune"
  }
}

Verify (Node.js)

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, headers, rawBody) {
  const timestamp = headers["x-edwyz-timestamp"];
  const given = headers["x-edwyz-signature"];
  if (!timestamp || !given) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = "sha256=" + createHmac("sha256", secret).update(timestamp + "." + rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(given);
  return a.length === b.length && timingSafeEqual(a, b);
}

Verify (Python)

import hmac, hashlib, time

def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
    ts = headers.get("x-edwyz-timestamp", "")
    given = headers.get("x-edwyz-signature", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    msg = ts.encode() + b"." + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, given)

Always compute the signature over the raw bytes you received, before any JSON parsing, compare in constant time, and reject timestamps more than five minutes old.