Eine Webhook-Adresse ist wie eine Tür. Jeder, der die Adresse kennt, kann ihr eine Anfrage senden. Wenn Sie die Adresse, an die Meta Nachrichtenereignisse sendet, nicht absichern, behandelt Ihr Ablauf ein gefälschtes Ereignis wie „Kunde hat bestellt“ oder „Zahlung bestätigt“ als echt. Meta fügt deshalb jeder Anfrage eine Signatur bei. In diesem Beitrag erklären wir, was diese Signatur ist und wie Sie sie in n8n prüfen. In türkischsprachigen Quellen sind wir auf dieses Thema kaum gestoßen; meist wird nur der Verifizierungsschritt bei der Ersteinrichtung beschrieben, die Signaturseite wird ausgelassen.
Kurze Antwort
Meta fügt jeder POST-Anfrage einen X-Hub-Signature-256-Header hinzu. Dies ist der HMAC-SHA256-Wert des Rohdaten-Bodys der Anfrage, berechnet mit Ihrem App-Secret (app secret). Sie führen dieselbe Berechnung in n8n durch und vergleichen sie mit dem Wert im Header; stimmt er nicht überein, verwerfen Sie die Anfrage, ohne sie zu verarbeiten. Der häufigste Fehler ist der Versuch, den Hash über das geparste JSON zu berechnen.
Es gibt zwei getrennte Prüfungen
Die beiden werden oft verwechselt. Die erste findet statt, wenn Sie den Webhook erstmals definieren: Meta sendet eine GET-Anfrage an Ihre Adresse, die hub.mode=subscribe, hub.verify_token und hub.challenge enthält. verify_token ist ein von Ihnen gewählter Text. Stimmt der eingehende Wert mit dem von Ihnen gespeicherten überein, geben Sie den Wert von hub.challenge mit dem Statuscode 200 zurück. Laut Meta-Dokumentation lässt jede andere Antwort, auch Codes der 400er-Reihe, die Adresse unverifiziert, und es kommen keine Webhooks an.
Die zweite ist die dauerhaft laufende Signaturprüfung, und sie sorgt für die eigentliche Sicherheit. verify_token wird nur einmal bei der Einrichtung abgefragt. Danach ist es die Signatur, die die Herkunft eingehender Nachrichtenereignisse bestätigt.
Wie entsteht die Signatur?
Das von Meta beschriebene Format lautet so: Der Wert des X-Hub-Signature-256-Headers beginnt mit „sha256=“, gefolgt von einem Hash. Dieser Hash ist ein HMAC-SHA256, der mithilfe des Request-Bodys und des geheimen Schlüssels Ihrer App berechnet wird. Sie müssen dieselbe Berechnung mit dem eingehenden Body und Ihrem eigenen geheimen Schlüssel durchführen und das Ergebnis mit dem Teil nach „sha256=“ im Header vergleichen. Stimmen sie überein, ist die Nutzlast laut Formulierung der Meta-Dokumentation gültig, und Sie geben 200 zurück; andernfalls geben Sie einen anderen Code als 200 zurück.
Der geheime Schlüssel ist der App-Secret-Wert, den Sie in den Einstellungen Ihrer App im Meta-for-Developers-Dashboard finden. Statt ihn als Klartext in den Workflow zu schreiben, ist es besser, ihn in der Credential-Verwaltung von n8n oder in einer Umgebungsvariablen aufzubewahren.
Warum der Rohdaten-Body unverzichtbar ist
HMAC hängt von den exakten Bytes des Bodys ab. Schon der Unterschied eines einzelnen Leerzeichens oder Escape-Zeichens erzeugt einen völlig anderen Hash. Der n8n-Webhook-Node parst eingehendes JSON automatisch; wenn Sie das geparste Objekt wieder in Text umwandeln, können sich Schlüsselreihenfolge, Leerzeichen und die Schreibweise von Sonderzeichen ändern. Ihr Ergebnis stimmt dann nicht mit dem von Meta verwendeten Format überein, und selbst eine korrekte Anfrage erscheint „ungültig“. Im n8n-Community-Forum gibt es aus genau diesem Grund einen Thread, in dem beschrieben wird, dass Signaturen nie übereinstimmen: Im Rohdaten-Body des Absenders waren die Schrägstriche escaped, im von n8n angezeigten Body nicht.
Die Lösung ist, den Hash über die rohen Bytes zu bilden. Der n8n-Webhook-Node bietet dafür die Option Raw Body. Die Dokumentation beschreibt diese Option so, dass der Node die Daten in Rohform wie JSON oder XML entgegennimmt. Laut einem Community-Beitrag werden bei aktivierter Option neben dem geparsten Body auch die Request-Bytes als Binärdaten vorgehalten. Da sich dieses Verhalten zwischen Versionen ändern kann, prüfen Sie es in Ihrem eigenen Setup mit einer Testanfrage.
Einrichtung in n8n
Das Grundgerüst des Ablaufs sieht so aus:
- Webhook-Node: Aktivieren Sie die Option Raw Body. Wenn Sie zwei getrennte Methoden verwenden, vereinfacht es die Arbeit, für GET (Verifizierung) und POST (Ereignisse) getrennte Pfade zu definieren.
- Signaturberechnung: Sie können die Hmac-Operation des Crypto-Knotens verwenden. Laut Dokumentation wird SHA256 unterstützt, und die Ausgabe kann HEX oder BASE64 sein. Da Meta den Hash als Hex sendet, wählen Sie HEX und übergeben Sie den Rohkörper als Eingabe. Wenn Sie den Code-Knoten bevorzugen, benötigen Sie das crypto-Modul von Node; aus Sicherheitsgründen schränkt n8n die Modulnutzung ein und verlangt die Einstellung NODE_FUNCTION_ALLOW_BUILTIN=crypto. Wenn Sie einen Task Runner verwenden, muss diese Einstellung im Task Runner vorgenommen werden, nicht im Haupt-Knoten.
- Vergleich: Entfernen Sie das Präfix "sha256=" vom Wert im Header und vergleichen Sie ihn mit dem berechneten Hex-Wert. Verwenden Sie nach Möglichkeit einen zeitkonstanten Vergleich; im Code-Knoten leistet crypto.timingSafeEqual dies.
- If-Knoten: Stoppen Sie bei einer nicht übereinstimmenden Anfrage den Ablauf und geben Sie mit Respond to Webhook einen 400er-Code zurück. Bei Übereinstimmung fahren Sie fort.
Der Webhook-Knoten antwortet standardmäßig sofort mit "Workflow got started". Wenn Sie je nach Signaturergebnis unterschiedliche Codes zurückgeben möchten, müssen Sie den Antwortmodus auf den Respond-to-Webhook-Knoten umstellen.
Wann sollte man Meta mit 200 antworten?
Laut Meta werden fehlgeschlagene Zustellungen sofort und danach 7 Tage lang in abnehmender Häufigkeit erneut versucht. Ist Ihr Ablauf also langsam oder liefert Fehler, kann dieselbe Nachricht mehrfach bei Ihnen eingehen. Zwei Maßnahmen helfen. Erstens: die Signatur prüfen und sofort 200 zurückgeben, aufwendige Aufgaben erst danach erledigen. Zweitens: die ID jeder Nachricht in einer Tabelle speichern und bereits verarbeitete überspringen. Meta weist außerdem darauf hin, dass Anfragen gebündelt eintreffen können, dass eine einzelne Anfrage bis zu 1000 Updates enthalten kann und dass dies nicht garantiert ist; verarbeiten Sie jede Anfrage einzeln und in einer Schleife.
Zusätzliche Schutzebenen
Die Signaturprüfung reicht zwar aus, doch es gibt Dinge, die Sie zusätzlich einsetzen können. Meta dokumentiert für Webhooks auch Unterstützung für gegenseitiges TLS (mTLS); es muss für jede App separat aktiviert werden. Auf der n8n-Seite bietet der Webhook-Knoten eine IP-Zulassungsliste, und Anfragen von außerhalb erhalten ein 403. Damit das funktioniert, müssen Sie jedoch die von Meta verwendeten Adressen aktuell halten, und die Adressliste kann sich ändern. Setzen Sie dies daher nicht anstelle der Signatur ein, sondern zusätzlich dazu. Der Endpunkt muss über ein gültiges TLS-Zertifikat verfügen; Meta unterstützt keine selbstsignierten Zertifikate.
Auch die Wahl des Hostings spielt hier eine Rolle. Bei n8n auf dem eigenen Server verwalten Sie Umgebungsvariablen, Reverse-Proxy-Einstellungen und Zertifikat selbst; in der Cloud verbleibt ein Teil davon beim Anbieter. Für einen Vergleich lesen Sie gern unseren Beitrag zu den Kosten von Self-Hosted und Cloud. Wo die über den Webhook eingehenden Kundendaten gespeichert werden, ist ein eigenes Thema: Wir haben es im Beitrag zur KVKK-konformen Automatisierung behandelt.
Ein praktischer Weg zum Testen
Richten Sie es zuerst mit der Test-URL ein, prüfen Sie, dass der richtige Hash berechnet wird, und wechseln Sie dann zur Production-URL. Laut n8n-Dokumentation ist der Test-Webhook nur im Listening-Modus registriert, die Production-Adresse dagegen, sobald der Workflow veröffentlicht ist. Ist im Meta-Dashboard die Production-Adresse hinterlegt, sieht ein Ablauf im Testmodus nichts. Verwenden Sie anschließend absichtlich einen falschen geheimen Schlüssel und prüfen Sie, ob die Signatur abgelehnt wird. Eine Verifizierung, deren Ablehnungsseite nicht getestet wurde, hat nicht bewiesen, dass sie funktioniert.
Es ist ratsam, dass dieses Fundament stabil ist, bevor Sie weiterführende Abläufe aufbauen, etwa die Verknüpfung von Nachrichten aus Anzeigen mit Verkäufen; die Werbeseite haben wir im Beitrag zu ctwa_clid behandelt.
Häufige Fragen
Ist die Überprüfung der WhatsApp-Webhook-Signatur verpflichtend?
Die Dokumentation von Meta beschreibt, dass Sie die Signatur prüfen und bei Gültigkeit 200 zurückgeben sollen. Wenn Sie nicht prüfen, kann jeder, der Ihre Webhook-Adresse kennt, ein gefälschtes Nachrichtenereignis senden, und Ihr Ablauf hält es für eine echte Kundennachricht.
Warum kann ich die Signatur nicht aus dem geparsten JSON berechnen?
Der HMAC wird über die exakten Bytes des Körpers berechnet. Wenn Sie das JSON parsen und neu schreiben, können sich Leerzeichen, Escape-Zeichen und die Feldreihenfolge ändern, und der Hash stimmt nicht überein. Deshalb muss mit dem Rohkörper gearbeitet werden.
Was passiert, wenn Meta dasselbe Ereignis mehrfach sendet?
Meta wiederholt fehlgeschlagene Zustellungen sofort und danach 7 Tage lang in abnehmender Häufigkeit. Ihr Ablauf darf daher dieselbe Nachrichten-ID kein zweites Mal verarbeiten.
Quellen: Meta for Developers, "Create a webhook endpoint" · n8n Docs, Webhook node · n8n Docs, Crypto node · n8n Docs, Modules in the Code node · n8n Community, Beispiel zur HMAC-Verifizierung · n8n Community, Problem mit dem Rohkörper. Oberfläche und Verhalten können sich je nach Version unterscheiden; testen Sie in Ihrer eigenen Umgebung.
Lassen Sie uns gemeinsam die Sicherheit Ihres Webhook-Ablaufs überprüfen
Lassen Sie uns die Signaturprüfung, doppelte Ereignisse und die Fehlerbehandlung in Ihrem WhatsApp-Ablauf in einer halben Stunde gemeinsam prüfen.