Webhooks

Get told when something happens instead of polling for it. Add an endpoint under Developer → Webhooks, or through the API above with a webhooks:manage key. Every endpoint gets a secret; every delivery is signed.

Events

Messenger events: chat.message, chat.message.edited, chat.message.deleted, chat.action, chat.operator_requested, lead.new, lead.updated, scenario.done|failed|cancelled, channel.connected|disconnected|revoked. The payload carries channel_id and the event data.

Payload

POST https://example.com/webhooks/sms
Content-Type: application/json
X-SMS-Event: message.delivered
X-SMS-Event-Id: evt_01k…
X-SMS-Delivery-Attempt: 1
X-SMS-Signature: t=1754825400,v1=8f3a…

{
  "event_id": "evt_01k…",
  "event": "message.delivered",
  "timestamp": "2026-08-11T09:30:00+00:00",
  "data": {
    "id": "msg_01k…",
    "status": "delivered",
    "to": "+998901234567",
    "segments": 1,
    "client_reference": "order_4389",
    "delivered_at": "2026-08-11T09:29:58+00:00"
  }
}

Verifying the signature

Compute HMAC SHA-256 over "{timestamp}.{raw body}" with your endpoint's secret. Sign the raw body — re-encoding the JSON first will change the bytes and the signature will not match. The timestamp is inside the signed string, which is what stops a captured payload being replayed later.

// PHP
$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_SMS_SIGNATURE'] ?? '';

parse_str(strtr($header, ',', '&'), $parts);

if (abs(time() - (int) $parts['t']) > 300) {
    http_response_code(400);   // too old, treat as replay
    exit;
}

$expected = hash_hmac('sha256', $parts['t'] . '.' . $raw, $secret);

if (! hash_equals($expected, $parts['v1'])) {
    http_response_code(401);
    exit;
}

// Node.js (express, raw body required)
app.post('/webhooks/sms', express.raw({ type: 'application/json' }), (req, res) => {
  const parts = Object.fromEntries(
    req.get('X-SMS-Signature').split(',').map((p) => p.split('=')),
  );

  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${parts.t}.${req.body}`)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))) {
    return res.sendStatus(401);
  }

  res.sendStatus(200);   // acknowledge fast, process afterwards
});

Retries

Any 2xx counts as delivered. Anything else is retried 1 min, 5 min, 30 min, 2 h after the first attempt. An endpoint that fails 20 times in a row is disabled automatically — re-enable it once it is fixed.

Every event carries a unique event_id. A retry reuses it, so store the ones you have processed and ignore repeats — a delivery that timed out on your side may still have been received.

Reply quickly. We wait 10 seconds; do the real work after responding, not before.

Per-message callbacks

Passing callback_url on a send delivers that message's events to that URL as well. Those are not signed — there is no shared secret behind a one-off URL — so treat them as a hint and confirm with GET /api/v1/messages/{id} before acting on anything that matters.