Skip to Content
Developer docsBeta

Webhooks

Get every status change and reply as it happens, and verify it came from Mawgood.

Instead of asking Mawgood for updates, give it a URL and it will tell you. Each workspace has one webhook endpoint (a public HTTPS URL), set by owners and admins in Mawgood › Settings › Developers with the events it wants and its signing secret.

Events fire for every campaign of the workspace, the ones made with the API and the ones made in the dashboard: source (api or dashboard) tells them apart.

Events

typeWhen
message.statusA message was queued, sent, delivered, read, failed, skipped or cancelled.
message.repliedA recipient replied (the first reply). The conversation continues in the inbox.
campaign.startedThe campaign started sending, including after the Mawgood team approved it.
campaign.rejectedThe Mawgood team didn't approve the campaign; data.reviewNote says why.
campaign.completedEvery message in the campaign was sent or skipped.
campaign.pausedThe campaign paused; data.pauseReason says why.
campaign.failedThe campaign couldn't run, or every message failed.
campaign.cancelledThe campaign was cancelled; messages not sent yet are cancelled first.
pingThe test event from Send test event. Always sent, whatever you picked.

Every event is a POST with a JSON body { id, type, createdAt, data }:

message.status
{
  "id": "evt_4Rt9Kp",
  "type": "message.status",
  "createdAt": "2026-11-20T10:15:04Z",
  "data": {
    "campaignId": "cmp_9Xa4Lr",
    "campaignName": "Order updates",
    "source": "api",
    "at": "2026-11-20T10:15:03Z",
    "recipient": {
      "phone": "+201001234567",
      "externalId": "order-1042",
      "name": "Mona",
      "status": "delivered",
      "error": null,
      "skipReason": null,
      "sentAt": "2026-11-20T10:15:01Z",
      "deliveredAt": "2026-11-20T10:15:03Z",
      "readAt": null,
      "repliedAt": null
    }
  }
}
message.replied
{
  "id": "evt_7Hc2Wq",
  "type": "message.replied",
  "createdAt": "2026-11-20T10:20:11Z",
  "data": {
    "campaignId": "cmp_9Xa4Lr",
    "phone": "+201001234567",
    "externalId": "order-1042",
    "repliedAt": "2026-11-20T10:20:11Z"
  }
}

recipient is the same object as in GET /campaigns/{id}/recipients. The reply's text is never sent: read it in the Mawgood inbox. campaign.* events carry the campaign as GET /campaigns/{id} returns it at that moment (status, pauseReason, reviewNote, counts…), and ping carries { "message": "Test event from Mawgood" }. The API reference has every payload.

Headers

HeaderValue
Content-Typeapplication/json
User-AgentMawgood-Webhooks/1
Mawgood-Event-IdThe event's id (evt_…).
Mawgood-Signaturet=<unix seconds>,v1=<hex>. See below.

Responding and retries

Return any 2xx within 10 seconds, then do the work: put the event in a queue, or process it after responding. Anything else (a 4xx, a 5xx, a timeout, a redirect) is a failure and is retried after about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours, then once more when the event is 24 hours old. After that it's failed.

Delivery is at least once, and events can arrive in any order:

  • Dedupe by id (also in Mawgood-Event-Id). The same event can arrive more than once. Store the ids you processed and skip repeats.
  • Expect any order. A read can arrive before its delivered. Compare createdAt (and the recipient's timestamps) with what you have, and never move a status backwards.
  • A campaign can send campaign.completed and then campaign.failed (when WhatsApp refuses every message after the last was handed over). Treat the latest campaign.* event by createdAt as the campaign's state.

If your endpoint keeps failing (50 failures in a row over more than a day), Mawgood switches it off, marks its waiting events failed and notifies the workspace owners. Fix it and switch it on again in Settings › Developers.

The delivery log

Settings › Developers › Webhook lists every event of the last 30 days with its status (pending, delivered, failed), attempts, last answer and the exact JSON posted. From there, Send again resends a failed event (same id and body, a new signature) and Send test event posts a ping. Both work while the endpoint is off.

The same log is in the API, with a key that has webhooks:manage:

curl "https://api.mawgood.ai/v1/webhooks/deliveries?status=failed" \
  -H "Authorization: Bearer $MAWGOOD_API_KEY"

It answers { "data": [...], "nextCursor": null }, latest first (limit up to 100).

Verify the signature

Every request has a Mawgood-Signature header:

Mawgood-Signature: t=1763633704,v1=5f2b9c…

v1 is the hex HMAC-SHA256 of "<t>.<raw body>", keyed with your endpoint's signing secret. To verify a request:

  1. Read the raw request body, before any JSON parsing.
  2. Split the header into t and its v1 values (there can be two, see below).
  3. Reject it if t is more than 5 minutes from now (a replayed request).
  4. Compute the HMAC of t + "." + rawBody and compare it with each v1 in constant time. Accept the request if one matches.
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.MAWGOOD_WEBHOOK_SECRET;

function verify(rawBody, header) {
  let t = 0;
  const signatures = [];
  for (const part of header.split(',')) {
    const [key, value = ''] = part.trim().split('=');
    if (key === 't') t = Number(value);
    if (key === 'v1' && value) signatures.push(value);
  }
  if (!t || signatures.length === 0) return false;
  if (Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes
  const expected = Buffer.from(
    crypto.createHmac('sha256', SECRET).update(`${t}.${rawBody}`).digest('hex'),
  );
  // After a secret rotation, a request can carry two v1 signatures: accept either.
  return signatures.some((sig) => {
    const given = Buffer.from(sig);
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

// express.raw keeps the body as bytes, exactly as Mawgood signed it.
app.post('/webhooks/mawgood', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body.toString('utf8'), req.get('Mawgood-Signature') ?? '')) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(req.body);
  res.sendStatus(200); // acknowledge first, then process
  handle(event);
});

Use the raw body

Parsing the JSON and serialising it again changes spaces and key order, and the signature won't match. Verify the bytes you received.

Rotating the secret

You can rotate the signing secret in Settings › Developers. The old secret stays valid for 24 hours, so you have time to update your server. During that window a request can carry two v1 signatures, one per secret:

Mawgood-Signature: t=1763633704,v1=5f2b9c…,v1=a81d07…

Verify against either one. The snippets above already accept a request when any v1 matches.

On this page