WhatsApp Webhooks Guide: Events, Security and Retries

{
  "messageId": "2603121407537573731",
  "channel": "SMS",
  "destination": "447700900123",
  "status": "DELIVERED",
  "timestamp": "2026-10-10T09:15:42Z",
  "reason": null
}

How do I write a reliable handler?

Do three things in order: store the raw event, acknowledge with a 2xx, then process asynchronously. The handler below follows the pattern in our docs.

import express from "express";

const app = express();

// Capture the raw body so you can store it exactly as received.
app.post(
  "/webhooks/omnichannels",
  express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); } }),
  async (req, res) => {
    try {
      await db.webhookEvents.insert({ receivedAt: new Date(), body: req.rawBody });
    } catch (err) {
      return res.sendStatus(500); // storage failed: let the event be retried
    }
    res.sendStatus(200);          // acknowledge fast
    queue.publish("status-events", req.body); // do the real work elsewhere
  },
);

// Worker: idempotent processing
async function processEvent(event) {
  const id = event.messageId ?? event.message_id ?? event.id; // map per channel
  const status = event.status;
  const rank = { SUBMITTED: 1, SENT: 2, DELIVERED: 3, READ: 4, FAILED: 4, REJECTED: 4 };

  const current = await db.messages.findOne({ providerId: id });
  if (!current) return; // unknown message: log it and investigate
  if ((rank[status] ?? 0) <= (rank[current.status] ?? 0)) return; // duplicate or stale

  await db.messages.update({ providerId: id }, { status, updatedAt: new Date() });
}

from datetime import datetime, timezone
from flask import Flask, request

app = Flask(__name__)

RANK = {"SUBMITTED": 1, "SENT": 2, "DELIVERED": 3, "READ": 4, "FAILED": 4, "REJECTED": 4}


@app.post("/webhooks/omnichannels")
def omnichannels_webhook():
    raw = request.get_data(as_text=True)
    try:
        db.webhook_events.insert({"received_at": datetime.now(timezone.utc), "body": raw})
    except Exception:
        return "", 500           # storage failed: let the event be retried
    queue.publish("status-events", raw)  # process asynchronously
    return "", 200               # acknowledge fast

The db and queue objects are your own storage and job queue. The rank map is what makes processing idempotent: a duplicate or stale event is not an advance, so it is ignored.

Rules for a reliable handler

• Respond within a few seconds. Do no heavy work before you respond.
• Return 2xx only after the event is stored. If storage fails, return 5xx.
• Deduplicate by message ID. The same status can arrive more than once.
• Never resend a message from the handler. Decide on retries in a separate job, after checking status.
• Keep the raw body for troubleshooting and for replaying events after a fix.

How do I secure a WhatsApp webhook?

It depends on who sends to your endpoint. Meta signs webhooks it sends to apps you register with Meta. The OmniChannels.ai API spec defines no webhook signature header, so do not wait for one.

For Meta's scheme, Meta's documentation says to generate an HMAC-SHA256 hash from the JSON payload using your app secret and compare it with the value after sha256= in the X-Hub-Signature-256 header. HMAC itself is defined in RFC 2104. Compute it over the raw bytes, not a re-serialised object, and compare in constant time.

For our endpoint:

• Use HTTPS only, with a valid certificate.
• Use a long, unguessable path, and rotate it if it leaks.
• Validate the body shape and reject anything unexpected.
• Treat events as notifications. Before an irreversible action, such as a refund or fraud lock, confirm the state with a polling call.

What happens when delivery fails?

Retries depend on the sender. Meta's documentation says it retries a failed delivery with decreasing frequency for up to 7 days, which can produce duplicate notifications. That is a reason to be idempotent even if you rarely see duplicates. For events from our platform, confirm retry behaviour with your onboarding engineer instead of assuming it matches Meta's.

Either way, build for loss as well as duplication: your endpoint can be down during a deploy, and a firewall rule can drop requests silently.

How do I recover missing events?

Poll the batch, do not resend the message.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&page=0&size=100" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id is the ID returned by the send call, and page is zero-based. Run a nightly reconciliation that reads the previous day's batches and fills any gaps.

Troubleshooting checklist

1. Is the URL configured on the right account or sub-account?
2. Is the endpoint reachable over HTTPS with a valid certificate?
3. Does it answer 2xx quickly, or time out?
4. Is a firewall or WAF rule blocking the requests?
5. Do you log the raw body before parsing, so a parser error cannot hide the event?

Worked example: a retailer's notification pipeline

"Souq Rafiq" (synthetic), a UAE retailer, sends order updates by WhatsApp and wants accurate status in its order tool.

1. Orders are sent with sendbulk, and the batchId is stored on the order. See send a WhatsApp message via API.
2. The webhook endpoint writes every event to a table, then returns 200.
3. A worker ranks statuses and updates the order's message state.
4. FAILED events create a task for support with the reason, and an SMS fallback is considered per channel fallback.
5. Inbound customer messages are routed to the shared inbox so agents can reply inside the window.
6. A nightly job calls bulk-insights for yesterday's batches and corrects anything missed.

What are the common mistakes?

• Heavy work before responding, which causes timeouts and repeated deliveries.
• Acknowledging before storing, which loses events when storage fails.
• Trusting order. A late SENT overwriting DELIVERED.
• Coding against the illustrative payload instead of real events.
• Re-serialising JSON before checking a signature, which changes the bytes.
• Resending from the handler, which can loop.
• Limits: this guide describes our documented behaviour. Retry policy and payload fields for your account should be confirmed during onboarding.

How OmniChannels.ai helps

OmniChannels.ai pushes delivery statuses and inbound messages for WhatsApp, SMS, RCS and other channels to your webhook in one normalised format, with separate webhooks per sub-account for resellers. BroadNet is an official Meta Business Solution Provider, so Meta's own webhook requirements are handled for you, and you work with our API. Read the webhooks reference and the WhatsApp API docs, or see how events appear in the shared inbox.