Einen WhatsApp-Webhook-Endpoint verifizieren
Bevor Meta ein Ereignis zustellt, ruft die Plattform Ihren Endpoint mit einer GET-Anfrage auf, die hub.mode, hub.verify_token und hub.challenge enthält. Ihr Endpoint muss das Token vergleichen und die Challenge als unveränderten Body zurückgeben. Alles andere verhindert den Beginn der Zustellung.
Der Wert, der als Antwort-Body zurückgegeben werden muss.
Der Wert von hub.mode bei einer Verifizierungsanfrage.
Das einzige Schema, das Meta verifiziert. HTTP wird vor dem Aufruf abgelehnt.
Was genau sendet Meta?
Eine GET-Anfrage an Ihre URL mit drei Query-Parametern. hub.mode ist auf subscribe gesetzt. hub.verify_token ist das Token, das Sie beim Einrichten des Ziels konfiguriert haben. hub.challenge ist ein Wert, den Meta für diesen Versuch erzeugt.
Ihr Endpoint sollte hub.verify_token mit dem von Ihnen gewählten Token vergleichen. Wenn beide übereinstimmen, antworten Sie mit 200 und hub.challenge als vollständigem Antwort-Body. Nicht in JSON verpackt, nicht in Anführungszeichen und nicht mit einem abschließenden Zeilenumbruch, den manche Frameworks standardmäßig hinzufügen.
Wenn das Token nicht übereinstimmt, antworten Sie mit 403. Das ist das gesamte Protokoll und bewusst kompakt gehalten.
Warum scheitert eine falsche Antwort unbemerkt?
Weil eine fehlgeschlagene Verifizierung kein Fehler in Ihrem System ist, sondern ein Ausbleiben in Metas System.
Wenn die Challenge nicht korrekt zurückgegeben wird, beginnt Meta einfach nicht mit der Zustellung an dieses Ziel. Ihr Server antwortet bei der Verifizierung mit 200, Ihre Logs zeigen eine eingegangene Anfrage und kein Dashboard meldet ein Problem. Das einzige Anzeichen ist, dass keine Nachrichten eintreffen. Meist wird das als Coexistence-Problem diagnostiziert und nicht als Problem beim Handshake.
Darum lohnt sich die Validierung vor dem Aufruf. Wir prüfen, ob die URL HTTPS verwendet und ein Verify-Token angegeben wurde, bevor wir die Graph-Anfrage senden. So schlägt ein fehlerhaftes Ziel sofort fehl, statt verbunden zu wirken.
Was kann die Verifizierung noch blockieren?
Drei Dinge, die nichts mit dem Code zu tun haben.
Eine Authentifizierung vor dem Endpoint. Ein Gateway, eine Basic-Auth-Schicht oder eine IP-Allowlist weist Metas Anfrage ab, und Meta kann keine Zugangsdaten vorlegen. Die Verifizierungsroute muss ohne diese Angaben erreichbar sein.
Eine Weiterleitung. Meta ruft die angegebene URL auf, und eine 301-Weiterleitung zu einem kanonischen Host wird nicht so verfolgt, dass der Handshake abgeschlossen wird. Geben Sie die endgültige URL an.
Und ein Framework, das die Antwort serialisiert. Wenn ein Handler einen String zurückgibt, der alles in JSON verpackt, enthält der Body Anführungszeichen um die Challenge und stimmt dadurch nicht überein.
Häufige Fehler
- JSON zurückgeben. Der Body muss der unveränderte Challenge-Wert ohne zusätzliche Zeichen sein.
- Den Endpoint hinter eine Authentifizierung stellen. Meta hat keine Zugangsdaten und wird abgewiesen.
- Meta eine URL geben, die weiterleitet. Verwenden Sie die endgültige URL.
EasyCoexistence prüft vor dem Aufruf von Meta, ob ein Ziel HTTPS verwendet und ein Verify-Token besitzt, und protokolliert einen fehlgeschlagenen Handshake in der Verbindungschronik, statt das Ziel zu verwerfen.
Häufig gestellte Fragen
Welches Token sollte ich verwenden?
Eine beliebige Zeichenfolge, die Sie wählen. Damit kann Ihr Endpoint Metas Anfrage von Anfragen anderer unterscheiden, die die URL kennen.
Wie oft findet die Verifizierung statt?
Bei der Einrichtung und erneut, sobald das Ziel festgelegt wird. Ein funktionierender Endpoint wird nicht bei jedem Ereignis erneut verifiziert.
Kann ich es selbst testen?
Ja. Rufen Sie Ihren eigenen Endpoint mit den drei Parametern auf und prüfen Sie, ob der Body exakt als Challenge-Wert zurückkommt.
Was passiert, wenn mein Server während der Verifizierung nicht erreichbar war?
Der Handshake schlägt fehl und das Ziel wird nicht aktiviert. Wenn Sie es erneut speichern, wird die Verifizierung wiederholt.
Weiterlesen
Bereit für den Start?
Richten Sie WhatsApp Coexistence in wenigen Minuten statt Monaten ein. Die App funktioniert weiterhin auf dem Telefon.
Kostenlose Testphase startenVerifiziert am