Docs Webhooks

Webhooks

Registering an endpoint, what a delivery is, checking its signature, and what to count on.

Documentation
curl -s -X POST $API/webhooks -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
     -d '{"url":"https://api.example.com/hooks/bonga","eventTypes":["message.created"]}'

The answer holds the endpoint's secret (whsec_…), shown then and when you ask for a new one (PATCH /webhooks/{id} with {"rotateSecret":true}). Leave eventTypes out for every event. An app has up to 10 endpoints; GET /webhooks/{id}/deliveries shows how the latest deliveries went, and POST /webhooks/{id}/test sends a webhook.test event (five at once, ten a minute). Bonga keeps the secret sealed under a key of its own.

A delivery is a POST with:

Content-Type: application/json
X-Bonga-Event: message.created
X-Bonga-Event-Id: 261009174512A1B2C3D4E5F6
X-Bonga-Delivery: 261009174512F6E5D4C3B2A1
X-Bonga-Signature: t=1791564312,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{ "id": "261009174512A1B2C3D4E5F6", "type": "message.created", "app": "duka",
  "createdAt": "2026-10-09T17:45:12.345Z", "data": { … } }

data is what a client gets for the same event (the table above; the events for clients alone — receipts, typing, presence, a user's own settings — are not sent). message.created carries more:

{ "message": { "id": "…", "seq": 7, "text": "@carol tukutane kesho", "sender": { "id": "alice", … }, … },
  "conversation": { "id": "…", "type": "GROUP", "title": "Chama", "externalId": null, … },
  "recipients": [
    { "userId": "bob",   "online": true,  "muted": false, "mentioned": false },
    { "userId": "carol", "online": false, "muted": true,  "mentioned": true } ] }

recipients is everybody in the conversation but the sender. Somebody with online: false had no connection when the message was sent: that is whom a push notification is for.

Checking the signature

v1 is the HMAC-SHA256, in hex, of t, a dot, and the body exactly as it arrived, under the endpoint's secret. Work it out over the raw bytes, before any JSON parsing, and turn away what is more than a few minutes old:

// Node, with Express: app.post('/hooks/bonga', express.raw({ type: 'application/json' }), handler)
const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(t + '.').update(rawBody).digest('hex');
  return v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}
// Java
static boolean verify(byte[] rawBody, String header, String secret) throws GeneralSecurityException {
    String t = header.substring(2, header.indexOf(','));
    String v1 = header.substring(header.indexOf("v1=") + 3);
    if (Math.abs(Instant.now().getEpochSecond() - Long.parseLong(t)) > 300)
        return false;
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    mac.update((t + ".").getBytes(StandardCharsets.UTF_8));
    String expected = HexFormat.of().formatHex(mac.doFinal(rawBody));
    return MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), v1.getBytes(StandardCharsets.UTF_8));
}

What to count on

  • Answer 2xx within 10 seconds. Anything else is tried again with a pause that doubles (30 seconds, a minute, two … up to an hour), eight attempts in all, then given up and kept for a month to look at (GET /webhooks/{id}/deliveries, whose lastError says what kind of failure it was). A delivery not made within a day is given up however few times it was tried.
  • An endpoint that keeps failing is paused: after five failed attempts in a row nothing is posted to it for a minute, twice as long after each failure that follows, half an hour at most, and the first attempt that arrives ends it. GET /webhooks shows pausedUntil meanwhile. Every app's events go through the one outbox: a node posts 32 deliveries at once, eight of one app at most, the apps taking turns, so a receiver that is slow, or never answers, holds up its own app's deliveries and nobody else's.
  • A delivery may arrive more than once (your answer can be lost). Every attempt of an event carries the same id: drop what you have seen.
  • Deliveries are not ordered. What they report carries its own order: a message its seq.
  • An event is queued in the transaction of the change it reports: your server never hears of something that was rolled back and never misses something that was not.
  • Endpoints are https and public: where the host points is checked as it is connected to, so a name that answers a public address first and a private one afterwards is still refused. Redirects are not followed.