Skip to content
Documentation

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

  1. 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).

  2. Add endpoint

    Enter an https:// URL on your server and choose the events, or All events.

  3. Copy the signing secret

    It starts with whsec_. Store it as an environment variable; you can reveal it again later, or rotate it.

  4. Send a test event

    Send test delivers a signed webhook.test event to that endpoint only. Check the Deliveries list for the response code.

A minimal receiver (Express)
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

EventFires when
whatsapp.message.receivedA customer sends a WhatsApp message to your number
whatsapp.message.statusA message you sent is sent, delivered, read or failed
whatsapp.template.statusMeta approves, rejects or pauses one of your templates
whatsapp.connection.updatedYour number is connected, registered or disconnected
wallet.creditedA top-up or saved-card charge lands in your prepaid balance
wallet.low_balanceYour prepaid balance falls below its low-balance threshold
plan.pausedA plan is paused because your prepaid balance could not cover its renewal
card.declinedAn automatic charge to your saved card is declined
team.member_joinedSomeone accepts an invite and joins your team

Every data object carries your accountId. Money is in kobo (integers) with currency: "NGN". Examples:

whatsapp.message.received
{
  "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.

whatsapp.message.status
{
  "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"
  }
}
wallet.credited
{
  "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:

HeaderWhat it is
webhook-idThe event’s id — the same on every retry and resend. Use it to ignore duplicates.
webhook-timestampWhen this attempt was signed, in Unix seconds
webhook-signaturev1, + 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.

Verify a webhook
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

  1. The secret is whsec_ followed by base64 of the key bytes — strip the whsec_ label and base64-decode the rest to get the HMAC key.
  2. Compute HMAC-SHA256 over webhook-id + . + webhook-timestamp + . + the raw body, and base64 it.
  3. Accept the request if v1, + that value equals any space-separated entry in webhook-signature (compare in constant time).
  4. Reject a webhook-timestamp more than 5 minutes (300 seconds) from your clock, so an old request can’t be replayed.
Verify by hand (Node.js)
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-id and skip ids you have already handled.
  • Events are not guaranteed to arrive in order — use data.at or timestamp when 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.