Webhooks
Receive customer messages, delivery updates and billing events on your own server, signed and retried.
Webhooks push what happens on your Darkel account to a URL on your server, the moment it happens. Use them to answer customers who message you, track delivery without polling, and react to billing changes.
Overview
You register one or more HTTPS endpoints and choose which events each one receives. When an event happens, Darkel sends a signed POST with a JSON body to every endpoint subscribed to it. If your server is down, Darkel keeps retrying.
Your code decides what to do
Darkel never replies to customers on your behalf. A webhook tells you a customer wrote; your server decides whether and how to answer — free text within 24 hours, or a template. See Replying to customers.
Set up an endpoint
Open Developers → Webhooks in the dashboard
You need the webhook manage permission, and read access to the data of every event you pick (for example billing access for prepaid-balance events).
Add endpoint
Enter an
https://URL on your server and choose the events, or All events.Copy the signing secret
It starts with
whsec_. Store it as an environment variable; you can reveal it again later, or rotate it.Send a test event
Send test delivers a signed
webhook.testevent to that endpoint only. Check the Deliveries list for the response code.
import express from "express";
import { Webhook } from "standardwebhooks";
const app = express();
const wh = new Webhook(process.env.DARKEL_WEBHOOK_SECRET); // whsec_… as-is
// Keep the raw body: the signature covers the exact bytes Darkel sent.
app.post("/darkel/webhooks", express.raw({ type: "application/json" }), (req, res) => {
let event;
try {
event = wh.verify(req.body.toString("utf8"), req.headers);
} catch {
return res.sendStatus(401);
}
res.sendStatus(200); // answer fast, then do the work
if (event.type === "whatsapp.message.received") {
console.log(event.data.from, "wrote:", event.data.text);
}
});
app.listen(3000);Reply with any 2xx within a few seconds and do slow work afterwards (or on a queue). Anything else, or no answer in 15 seconds, counts as a failure and is retried.
Events
| Event | Fires when |
|---|---|
whatsapp.message.received | A customer sends a WhatsApp message to your number |
whatsapp.message.status | A message you sent is sent, delivered, read or failed |
whatsapp.template.status | Meta approves, rejects or pauses one of your templates |
whatsapp.connection.updated | Your number is connected, registered or disconnected |
wallet.credited | A top-up or saved-card charge lands in your prepaid balance |
wallet.low_balance | Your prepaid balance falls below its low-balance threshold |
plan.paused | A plan is paused because your prepaid balance could not cover its renewal |
card.declined | An automatic charge to your saved card is declined |
team.member_joined | Someone accepts an invite and joins your team |
Every data object carries your accountId. Money is in kobo (integers) with currency: "NGN". Examples:
{
"type": "whatsapp.message.received",
"timestamp": "2026-11-16T09:59:00.000Z",
"data": {
"accountId": "6740f0c2a1b2c3d4e5f60718",
"messageId": "6740f1d0a1b2c3d4e5f60720",
"wamid": "wamid.HBgNMjM0ODAxMjM0NTY3OBUCABIYFjNFQjA",
"from": "2348012345678",
"type": "text",
"text": "Are you open today?",
"message": { "from": "2348012345678", "id": "wamid.HBgN…", "timestamp": "1763287140", "type": "text", "text": { "body": "Are you open today?" } }
}
}message is the WhatsApp message exactly as Meta sent it — for a photo or voice note it carries type, the caption and Meta’s media id, though the file itself isn’t available through Darkel.
{
"type": "whatsapp.message.status",
"timestamp": "2026-11-16T10:00:05.000Z",
"data": {
"accountId": "6740f0c2a1b2c3d4e5f60718",
"messageId": "6740f1e2a1b2c3d4e5f60731",
"wamid": "wamid.HBgNMjM0ODAxMjM0NTY3OBUCABEYEjQw",
"to": "+2348012345678",
"status": "delivered",
"error": null,
"at": "2026-11-16T10:00:04.000Z"
}
}{
"type": "wallet.credited",
"timestamp": "2026-11-16T10:02:00.000Z",
"data": {
"accountId": "6740f0c2a1b2c3d4e5f60718",
"amountKobo": 500000,
"currency": "NGN",
"source": "topup",
"balanceKobo": 1250000
}
}Payload & headers
The body is always { "type", "timestamp", "data" }. Three headers come with it, following the Standard Webhooks spec:
| Header | What it is |
|---|---|
webhook-id | The event’s id — the same on every retry and resend. Use it to ignore duplicates. |
webhook-timestamp | When this attempt was signed, in Unix seconds |
webhook-signature | v1, + a base64 HMAC-SHA256. Several space-separated values appear while a rotated secret overlaps. |
Verifying signatures
Use the official Standard Webhooks library for your language: give it the whsec_… secret exactly as the dashboard shows it, the raw request body and the headers. It checks the signature, rejects requests more than 5 minutes old, and handles the overlap while a secret is being rotated.
import { Webhook } from "standardwebhooks"; // npm i standardwebhooks
// Paste the whsec_… secret as-is.
const wh = new Webhook(process.env.DARKEL_WEBHOOK_SECRET);
// rawBody: the request body exactly as received, before any JSON parsing.
// Returns the parsed event, or throws if the signature or timestamp is wrong.
const event = wh.verify(rawBody, headers);Use the raw body
The signature covers the exact bytes Darkel sent. Verify before parsing — JSON you parsed and re-serialised will not match.
Without a library
- The secret is
whsec_followed by base64 of the key bytes — strip thewhsec_label and base64-decode the rest to get the HMAC key. - Compute HMAC-SHA256 over
webhook-id+.+webhook-timestamp+.+ the raw body, and base64 it. - Accept the request if
v1,+ that value equals any space-separated entry inwebhook-signature(compare in constant time). - Reject a
webhook-timestampmore than 5 minutes (300 seconds) from your clock, so an old request can’t be replayed.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, before any JSON parsing.
export function verifyWebhook(headers, rawBody, secret) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"];
if (!id || !timestamp || !signatures) return false;
// Reject anything more than 5 minutes (300 s) old or ahead: stops replays.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
// The secret is "whsec_" + base64 of the key bytes; the prefix is only a label.
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = Buffer.from(
"v1," +
crypto
.createHmac("sha256", key)
.update(`${id}.${timestamp}.${rawBody}`)
.digest("base64")
);
// Several signatures appear while a rotated secret overlaps; any match is fine.
return signatures.split(" ").some((sig) => {
const given = Buffer.from(sig);
return (
given.length === expected.length &&
crypto.timingSafeEqual(given, expected)
);
});
}Retries & duplicates
- A failed delivery is retried up to 10 attempts with growing waits, for up to about two days.
- An endpoint that keeps failing for 5 days is disabled automatically; fix it, then switch it back on in the dashboard.
- The same event can reach you more than once (a retry after a slow 2xx, a manual resend). Store the
webhook-idand skip ids you have already handled. - Events are not guaranteed to arrive in order — use
data.atortimestampwhen order matters.
Delivery log & resending
Developers → Webhooks lists every delivery for the last 30 days with its status, response code and attempts. Open one to see each attempt and the exact payload, and Resend it. Resend failed replays only failed deliveries from the last hour, day or week — useful after an outage — so customers your bot already answered aren’t answered twice.
Replying to customers
Within 24 hours of a customer’s last message to you, send free text with POST /v1/whatsapp/messages and { "to", "text": { "body" } } — Darkel doesn’t charge for it. After the window closes, send an approved template instead. See Send a message.