Facebook-Webhook-Verifizierung: hub.challenge und X-Hub-Signature-256
Facebook verifiziert einen Webhook-Endpoint mit einem GET, das hub.mode auf subscribe, hub.verify_token und hub.challenge enthält. Der Endpoint prüft das Token gegen das im App Dashboard hinterlegte und gibt die Challenge als Body zurück. Jedes Event kommt danach als POST, signiert im Header X-Hub-Signature-256: sha256= gefolgt vom HMAC-SHA256 der Payload, mit dem App-Secret als Schlüssel.
easyCoexistence übernimmt Metas Seite für jede Page, die Sie verbinden: Die App beantwortet hub.challenge, prüft X-Hub-Signature-256 und abonniert die Page für feed, messages und mention.
Der Wert, den hub.mode in Metas Verifizierungsanfrage immer trägt; hub.challenge ist eine Ganzzahl, die zurückgesendet wird.
Präfix von X-Hub-Signature-256, gefolgt von der SHA256-Signatur, die Meta aus der Payload und dem App-Secret erzeugt.
Wie schnell ein Messenger-Webhook-Endpoint jede Benachrichtigung mit 200 OK beantworten sollte.
Anzahl fehlgeschlagener Zustellungen, bevor eine Webhooks Disabled-Meldung erscheint und die App von der Page abgemeldet wird.
Wie lange Meta eine fehlgeschlagene Page-Benachrichtigung mit abnehmender Häufigkeit wiederholt, bevor sie verworfen wird.
Was enthält die Verifizierungsanfrage von Meta?
Ein GET an die Callback-URL, gesendet, sobald das Produkt Webhooks im App Dashboard konfiguriert wird oder ein Abonnement über /{app-id}/subscriptions angelegt wird. Drei Query-Parameter kommen mit:
- hub.mode: immer subscribe.
- hub.challenge: eine Ganzzahl, die der Endpoint zurücksenden muss.
- hub.
verify_token: die Zeichenkette aus dem Feld Verify Token im Dashboard. - PHP wandelt die Punkte in Unterstriche um, daher heißen sie dort
hub_mode,hub_challengeundhub_verify_token.
Wie soll der Endpoint darauf antworten?
Mit einem 200, dessen gesamter Body der hub.challenge-Wert ist, aber nur, wenn hub.mode subscribe ist und hub.verify_token übereinstimmt. Alles andere erhält einen 403, wie in Metas Beispiel-App. Das Dashboard zeigt, ob der Endpoint bestanden hat, und /{app-id}/subscriptions antwortet mit Erfolg oder Fehler. Der Endpoint braucht HTTPS mit einem gültigen TLS- oder SSL-Zertifikat, da selbstsignierte Zertifikate nicht unterstützt werden.
Wie wird X-Hub-Signature-256 berechnet?
Als HMAC-SHA256 der Payload, mit dem App-Secret der App als Schlüssel, in Kleinbuchstaben-Hex nach sha256=. Metas Messenger-Anleitung ergänzt, dass die Signatur die Payload mit Unicode-Escapes berücksichtigt, sodass eine Zeichenkette wie äöå als \u00e4\u00f6\u00e5 zählt. Hashen Sie deshalb den rohen Body exakt so, wie er empfangen wurde, niemals eine dekodierte oder neu serialisierte Kopie. Meta sagt, die Prüfung sei optional, empfiehlt sie aber dringend.
Wie prüft man das im Code?
Rohe Bytes aufbewahren, den HMAC berechnen, in konstanter Zeit vergleichen und erst dann parsen. Flasks get_data gibt den Body unverändert zurück, und genau darüber wurde die Signatur berechnet. Wer zuerst parst und dann neu serialisiert, ändert die Bytes. Ein kleiner Endpoint, der die Verifizierung beantwortet und jeden POST prüft:
import hashlib, hmac, os
from flask import Flask, abort, request
app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()
@app.get("/webhooks/facebook")
def verify():
token = request.args.get("hub.verify_token", "")
if request.args.get("hub.mode") == "subscribe" and hmac.compare_digest(token.encode(), VERIFY_TOKEN.encode()):
return request.args.get("hub.challenge", ""), 200
abort(403)
@app.post("/webhooks/facebook")
def receive():
raw = request.get_data() # the bytes Meta signed
expected = "sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected.encode(), request.headers.get("X-Hub-Signature-256", "").encode()):
abort(401)
# answer at once; hand request.get_json() to a queue for the work
return "EVENT_RECEIVED", 200Was erwartet Meta nach der Verifizierung?
Ein 200 OK für jede Benachrichtigung, bei Messenger-Events innerhalb von 5 Sekunden. Meta bündelt bis zu 1,000 Updates pro Zustellung, ohne dies zu garantieren, und behandelt Fehler so:
- Page-Benachrichtigungen: sofort erneut versucht, dann einige Male mit abnehmender Häufigkeit über 36 Stunden, danach verworfen.
- Messenger-Benachrichtigungen: einige Male sofort erneut versucht. Nach 15 Minuten Fehlern geht eine Warnung an das Entwicklerkonto.
- Nach einer Stunde Fehlern folgt eine Webhooks Disabled-Warnung, und die App wird von der Page abgemeldet, bis sie sich erneut anmeldet.
- Wiederholungen können ein Event doppelt und außer der Reihe zustellen. Deduplizieren Sie daher und sortieren Sie Nachrichten nach ihrem Zeitstempel.
- Vergangene Benachrichtigungen lassen sich später nicht abfragen. Speichern Sie deshalb, was Sie brauchen, sobald es eintrifft.
Wie besteht easyCoexistence Metas Prüfungen?
Die Meta-App von easyCoexistence hat eine Callback-URL für die verbundenen Pages, und dieser Endpoint führt beide Prüfungen selbst durch. Er beantwortet das GET nur, wenn hub.mode subscribe ist und das Verify Token übereinstimmt, verglichen in konstanter Zeit. Sonst gibt er 403 zurück. Jeden POST liest er als Rohtext, berechnet X-Hub-Signature-256 mit seinem App-Secret neu und weist eine Abweichung mit 401 ab. Meta antwortet er sofort, das Event wird erst danach verarbeitet.
Wie signiert easyCoexistence, was es weiterleitet?
Mit einer eigenen Signatur, denn Metas Header lässt sich nur mit dem App-Secret von easyCoexistence prüfen und wird nicht weitergegeben. Jeder Eintrag einer verbundenen Page mit gesetztem Endpoint wird als JSON dorthin gesendet, {platform, account_id, external_id, entry}, mit einem Header X-EC-Signature in der Form t=<unix>,v1=<hex>. Dabei ist v1 der HMAC-SHA256 aus Zeitstempel, einem Punkt und dem rohen Body, mit dem Signing-Secret dieser Page als Schlüssel:
- Das Secret beginnt mit whsec_ und wird einmal angezeigt, über
set_social_webhook_destinationoder PUT /channels/:id/webhook in der Partner API. - Wird die URL erneut gesetzt, entsteht ein neues Secret. Eine null-URL schaltet die Weiterleitung ab.
- Jede Weiterleitung wird einmal gesendet, mit bis zu 8 Sekunden Wartezeit, ohne Redirects zu folgen, an eine HTTPS-Adresse, die auf eine öffentliche IP aufgelöst wird.
- Eine Kopie des Events wird nicht gespeichert, daher gibt es nichts, was erneut versucht werden könnte.
Wie prüft man X-EC-Signature?
Den Header in t und v1 aufteilen und einen Zeitstempel verwerfen, der älter als 5 Minuten ist. Den HMAC über t, einen Punkt und den rohen Body mit dem Signing-Secret der Page neu berechnen und in konstanter Zeit vergleichen. In Node.js, mit dem Body als rohe Bytes:
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.EC_SIGNING_SECRET; // whsec_..., shown once
app.post("/events/facebook", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
String(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("="))
);
const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
const expected = crypto
.createHmac("sha256", SECRET)
.update(Buffer.concat([Buffer.from(`${sig.t}.`), req.body]))
.digest("hex");
const ok = fresh && typeof sig.v1 === "string" && sig.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
if (!ok) return res.sendStatus(401);
res.sendStatus(200); // answer first: forwards are not retried
const { platform, account_id, external_id, entry } = JSON.parse(req.body.toString("utf8"));
// queue entry for the work
});Häufige Fehler
- Den hub.challenge in JSON oder Anführungszeichen einzupacken. Der Body der 200-Antwort muss der Challenge-Wert selbst sein.
- Den HMAC nach einem JSON-Parser zu berechnen. Parsen und erneutes Serialisieren ändert die Bytes, und Meta signiert die Payload mit Unicode-Escapes. Deshalb den rohen Body hashen.
- Die Arbeit vor der Antwort zu erledigen. Messenger erwartet ein 200 innerhalb von 5 Sekunden, und eine Stunde Fehler meldet die App von der Page ab.
- Metas Signatur bei weitergeleiteten Events zu prüfen. Meta signiert mit dem App-Secret von easyCoexistence. Ein weitergeleitetes Event trägt X-EC-Signature, geprüft wird es mit dem Signing-Secret der Page.
Anschließend leitet sie die Events an Ihren HTTPS-Endpoint weiter, signiert mit X-EC-Signature und einem Secret für diese Page. US$ 9 bis US$ 0.75 pro Verbindung und Monat, sinkend mit jeder weiteren Verbindung, die ersten 3 Tage kostenlos.
Häufig gestellte Fragen
Woher stammt das Verify Token?
Sie wählen es selbst. Es ist die Zeichenkette im Feld Verify Token bei der Konfiguration der Webhooks im App Dashboard oder das verify_token, das an /{app-id}/subscriptions gesendet wird.
Kann ich die Verifizierung mit curl testen?
Ja. Metas Messenger-Anleitung sendet ein GET mit hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED und hub.mode=subscribe. Ein funktionierender Endpoint antwortet mit CHALLENGE_ACCEPTED.
Was passiert, wenn mein Endpoint eine Stunde lang ausfällt?
Meta sendet eine Webhooks Disabled-Warnung und meldet die App von der Page ab. Nach der Behebung am Endpoint abonnieren Sie die Page erneut über subscribed_apps.
Brauche ich meine eigene Meta-App, um Webhooks einer Page zu empfangen?
Mit easyCoexistence nicht. Meta liefert an die eigene App, die die Events jeder Page an den von Ihnen gesetzten Endpoint weiterleitet, signiert mit X-EC-Signature.
Weiterlesen
Verbinden Sie Ihren ersten Kanal in zwei Minuten.
Keine Plattform-Prüfungen, auf die Sie warten müssen. Verbinden Sie WhatsApp, Instagram, TikTok oder einen anderen Kanal, bitten Sie dann Ihre KI, zu posten, zu antworten oder Berichte zu erstellen, und sehen Sie ihr bei der Arbeit zu.
- 3 Tage kostenlos
- Jederzeit kündbar
- Nur offizielle APIs
- Überwacht rund um die Uhr (24/7)
Verifiziert am