WhatsApp-Webhooks: Ereignisse, Sicherheit und Wiederholungen

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

Wie schreibe ich einen zuverlässigen Handler?

Tun Sie drei Dinge in dieser Reihenfolge: das Roh-Ereignis speichern, mit einem 2xx bestätigen, dann asynchron verarbeiten. Der folgende Handler folgt dem Muster aus unserer Dokumentation.

import express from "express";

const app = express();

// Den Roh-Body erfassen, um ihn exakt wie empfangen zu speichern.
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); // Speichern fehlgeschlagen: Ereignis wiederholen lassen
    }
    res.sendStatus(200);          // schnell bestätigen
    queue.publish("status-events", req.body); // die eigentliche Arbeit woanders erledigen
  },
);

// Worker: idempotente Verarbeitung
async function processEvent(event) {
  const id = event.messageId ?? event.message_id ?? event.id; // je Kanal zuordnen
  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; // unbekannte Nachricht: protokollieren und untersuchen
  if ((rank[status] ?? 0) <= (rank[current.status] ?? 0)) return; // Duplikat oder veraltet

  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           # Speichern fehlgeschlagen: Ereignis wiederholen lassen
    queue.publish("status-events", raw)  # asynchron verarbeiten
    return "", 200               # schnell bestätigen

Die Objekte db und queue sind Ihr eigener Speicher und Ihre eigene Job-Warteschlange. Die rank-Map macht die Verarbeitung idempotent: Ein Duplikat oder veraltetes Ereignis ist kein Fortschritt und wird ignoriert.

Regeln für einen zuverlässigen Handler

• Antworten Sie innerhalb weniger Sekunden. Erledigen Sie vor der Antwort keine aufwendige Arbeit.
• Geben Sie 2xx erst zurück, nachdem das Ereignis gespeichert ist. Schlägt das Speichern fehl, geben Sie 5xx zurück.
• Deduplizieren Sie nach Nachrichten-ID. Derselbe Status kann mehrfach eintreffen.
• Senden Sie nie eine Nachricht aus dem Handler erneut. Entscheiden Sie über Wiederholungen in einem separaten Job, nach Prüfung des Status.
• Bewahren Sie den Roh-Body auf für die Fehlersuche und um Ereignisse nach einer Korrektur wiederzugeben.

Wie sichere ich einen WhatsApp-Webhook ab?

Das hängt davon ab, wer an Ihren Endpunkt sendet. Meta signiert Webhooks, die es an bei Meta registrierte Apps sendet. Die API-Spezifikation von OmniChannels.ai definiert keinen Webhook-Signatur-Header, warten Sie also nicht auf einen.

Zu Metas Verfahren sagt Metas Dokumentation, dass Sie aus der JSON-Payload mit Ihrem App Secret einen HMAC-SHA256-Hash erzeugen und mit dem Wert nach sha256= im Header X-Hub-Signature-256 vergleichen. HMAC selbst ist in RFC 2104 definiert. Berechnen Sie ihn über die Roh-Bytes, nicht über ein neu serialisiertes Objekt, und vergleichen Sie in konstanter Zeit.

Für unseren Endpunkt:

• Nutzen Sie ausschließlich HTTPS mit gültigem Zertifikat.
• Verwenden Sie einen langen, nicht erratbaren Pfad und tauschen Sie ihn aus, wenn er bekannt wird.
• Validieren Sie die Form des Bodys und weisen Sie Unerwartetes ab.
• Behandeln Sie Ereignisse als Benachrichtigungen. Bestätigen Sie vor einer unumkehrbaren Aktion wie einer Erstattung oder Betrugssperre den Zustand mit einem Abruf.

Was passiert, wenn die Zustellung fehlschlägt?

Wiederholungen hängen vom Absender ab. Metas Dokumentation sagt, dass eine fehlgeschlagene Zustellung mit abnehmender Häufigkeit bis zu 7 Tage lang wiederholt wird, was doppelte Benachrichtigungen erzeugen kann. Das ist ein Grund, idempotent zu sein, auch wenn Sie selten Duplikate sehen. Klären Sie das Wiederholungsverhalten für Ereignisse unserer Plattform mit Ihrem Onboarding-Ingenieur, statt anzunehmen, dass es dem von Meta entspricht.

Bauen Sie in jedem Fall auf Verlust ebenso wie auf Duplikate: Ihr Endpunkt kann während eines Deployments ausfallen, und eine Firewall-Regel kann Anfragen stillschweigend verwerfen.

Wie stelle ich fehlende Ereignisse wieder her?

Fragen Sie den Batch ab, senden Sie die Nachricht nicht erneut.

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

batch_Id ist die vom Sendeaufruf zurückgegebene ID, und page ist nullbasiert. Führen Sie einen nächtlichen Abgleich durch, der die Batches des Vortags liest und Lücken füllt.

Checkliste zur Fehlersuche

1. Ist die URL im richtigen Account oder Unterkonto konfiguriert?
2. Ist der Endpunkt über HTTPS mit gültigem Zertifikat erreichbar?
3. Antwortet er schnell mit 2xx oder läuft er in ein Timeout?
4. Blockiert eine Firewall- oder WAF-Regel die Anfragen?
5. Protokollieren Sie den Roh-Body vor dem Parsen, damit ein Parserfehler das Ereignis nicht verbirgt?

Praxisbeispiel: die Benachrichtigungs-Pipeline eines Händlers

„Souq Rafiq“ (fiktiv), ein Händler in den VAE, sendet Bestellupdates per WhatsApp und möchte in seinem Bestell-Tool einen korrekten Status sehen.

1. Bestellungen werden mit sendbulk gesendet, und die batchId wird an der Bestellung gespeichert. Siehe WhatsApp-Nachricht per API senden.
2. Der Webhook-Endpunkt schreibt jedes Ereignis in eine Tabelle und gibt dann 200 zurück.
3. Ein Worker ordnet Status nach Rang und aktualisiert den Nachrichtenstatus der Bestellung.
4. FAILED-Ereignisse erzeugen eine Aufgabe für den Support mit dem Grund, und ein SMS-Fallback wird gemäß Kanal-Fallback erwogen.
5. Eingehende Kundennachrichten werden in die Shared Inbox geleitet, damit Mitarbeiter im Fenster antworten können.
6. Ein nächtlicher Job ruft bulk-insights für die Batches des Vortags auf und korrigiert Verpasstes.

Welche typischen Fehler gibt es?

• Aufwendige Arbeit vor der Antwort, was Timeouts und wiederholte Zustellungen verursacht.
• Bestätigen vor dem Speichern, was Ereignisse verliert, wenn das Speichern fehlschlägt.
• Der Reihenfolge vertrauen. Ein verspätetes SENT überschreibt DELIVERED.
• Gegen die illustrative Payload programmieren statt gegen echte Ereignisse.
• JSON vor der Signaturprüfung neu serialisieren, was die Bytes verändert.
• Aus dem Handler erneut senden, was Schleifen verursachen kann.
• Grenzen: Dieser Leitfaden beschreibt unser dokumentiertes Verhalten. Wiederholungsregel und Payload-Felder für Ihren Account sollten Sie beim Onboarding bestätigen.

So unterstützt OmniChannels.ai

OmniChannels.ai sendet Zustellstatus und eingehende Nachrichten für WhatsApp, SMS, RCS und weitere Kanäle in einem einheitlichen, normalisierten Format an Ihren Webhook, mit getrennten Webhooks je Unterkonto für Reseller. BroadNet ist ein offizieller Meta Business Solution Provider, daher werden Metas eigene Webhook-Anforderungen für Sie erledigt, und Sie arbeiten mit unserer API. Lesen Sie die Webhooks-Referenz und die WhatsApp-API-Dokumentation oder sehen Sie, wie Ereignisse in der Shared Inbox erscheinen.