WhatsApp API

Webhooks

Register HTTPS endpoints to receive events. Payloads are signed with HMAC-SHA256 using your webhook secret.

Events

  • message.received
  • message.sent
  • message.delivered
  • message.read
  • message.failed
  • instance.connected
  • instance.disconnected

Create webhook

POST https://whatsapp.s.co.tz/api/v1/webhooks
Authorization: Bearer sk_live_xxx

{
  "url": "https://your-app.com/webhooks/whatsapp",
  "events": ["message.received", "instance.connected"]
}

// Response includes secret once:
// { "secret": "whsec_..." }

Verify signatures

Headers on each delivery:

  • X-Webhook-Id
  • X-Webhook-Timestamp
  • X-Webhook-Signature — format sha256=<hex>
const crypto = require('crypto');

function verify(rawBody, timestamp, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody)
    .digest('hex');
  return signature === 'sha256=' + expected;
}

Payload shape

{
  "id": "delivery-uuid",
  "event": "message.received",
  "created_at": "2026-08-19T12:00:00.000Z",
  "data": {
    "instance_id": "inst_xxx",
    "event": "message.received",
    "data": { ... },
    "timestamp": "2026-08-19T12:00:00.000Z"
  }
}