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
2xxwithin 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, whoselastErrorsays 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 /webhooksshowspausedUntilmeanwhile. 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
httpsand 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.