Weryfikacja webhooka Facebooka: hub.challenge i X-Hub-Signature-256
Facebook weryfikuje endpoint webhooka żądaniem GET z hub.mode ustawionym na subscribe, hub.verify_token i hub.challenge. Endpoint sprawdza token z tym z App Dashboard i zwraca challenge jako treść odpowiedzi. Każde zdarzenie przychodzi potem jako POST podpisane w nagłówku X-Hub-Signature-256: sha256= oraz HMAC-SHA256 payloadu, kluczowany sekretem aplikacji.
easyCoexistence obsługuje stronę Meta dla każdej Page, którą podłączasz: jego aplikacja odpowiada na hub.challenge, sprawdza X-Hub-Signature-256 i subskrybuje Page do feedu, wiadomości i wzmianek.
Wartość, jaką hub.mode zawsze niesie w żądaniu weryfikacyjnym Meta; hub.challenge to liczba całkowita, którą trzeba odesłać.
Prefiks X-Hub-Signature-256, po którym następuje podpis SHA256, jaki Meta generuje z payloadu i App Secret.
Jak szybko endpoint webhooka Messengera powinien odpowiedzieć na każde powiadomienie kodem 200 OK.
Liczba nieudanych dostaw, po której pojawia się alert Webhooks Disabled i aplikacja zostaje wypisana z Page.
Jak długo Meta ponawia nieudane powiadomienie Page, z coraz rzadszymi próbami, zanim je porzuci.
Co zawiera żądanie weryfikacyjne Meta?
GET na adres URL callbacku, wysyłany zawsze, gdy produkt Webhooks jest skonfigurowany w App Dashboard albo gdy subskrypcja powstaje przez /{app-id}/subscriptions. Towarzyszą mu trzy parametry zapytania:
- hub.mode: zawsze subscribe.
- hub.challenge: liczba całkowita, którą endpoint musi odesłać.
- hub.
verify_token: ciąg wpisany w polu Verify Token w panelu aplikacji. - PHP zamienia kropki na podkreślenia, więc odczytuje je jako
hub_mode,hub_challengeihub_verify_token.
Jak endpoint ma na to odpowiedzieć?
Kodem 200, którego całą treścią jest wartość hub.challenge, ale tylko wtedy, gdy hub.mode to subscribe, a hub.verify_token się zgadza. W każdym innym przypadku zwraca 403, tak jak przykładowa aplikacja Meta. Panel informuje, czy endpoint przeszedł, a /{app-id}/subscriptions odpowiada sukcesem albo błędem. Endpoint wymaga HTTPS z ważnym certyfikatem TLS lub SSL, bo certyfikaty samopodpisane nie są obsługiwane.
Jak liczy się X-Hub-Signature-256?
Jako HMAC-SHA256 payloadu żądania, kluczowany App Secret aplikacji, zapisany małymi literami w postaci heksadecymalnej po sha256=. Przewodnik Meta po Messengerze dodaje, że podpis obejmuje payload z escape'owanymi znakami Unicode, więc ciąg taki jak äöå liczy się jako \u00e4\u00f6\u00e5. Haszuj surowe ciało dokładnie tak, jak przyszło, nigdy zdekodowaną ani ponownie zserializowaną kopię. Meta mówi, że walidacja jest opcjonalna, ale mocno ją zaleca.
Jak to sprawdzić w kodzie?
Zachowaj surowe bajty, policz HMAC, porównaj w stałym czasie, dopiero potem parsuj. Metoda get_data z Flaska zwraca ciało nietknięte, czyli dokładnie to, z czego liczono podpis. Najpierw sparsowanie, a potem ponowna serializacja zmieniłyby bajty. Mały endpoint, który odpowiada na weryfikację i sprawdza każdy POST:
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", 200Czego Meta oczekuje po weryfikacji?
Odpowiedzi 200 OK na każde powiadomienie, w ciągu 5 sekund dla zdarzeń Messengera. Meta grupuje do 1 000 aktualizacji w jednej dostawie, bez gwarancji, i obsługuje błędy tak:
- Powiadomienia Page: ponawiane od razu, potem jeszcze kilka razy z coraz rzadszymi próbami przez 36 godzin, a następnie porzucane.
- Powiadomienia Messengera: ponawiane kilka razy od razu. Po 15 minutach błędów alert trafia na konto dewelopera.
- Po godzinie błędów pojawia się alert Webhooks Disabled, a aplikacja zostaje wypisana z Page, dopóki znów się nie zasubskrybuje.
- Ponowienia mogą dostarczyć zdarzenie dwukrotnie i w złej kolejności, więc deduplikuj i sortuj wiadomości według znacznika czasu.
- Dawnych powiadomień nie da się zapytać później, więc zapisuj to, czego potrzebujesz, w miarę jak przychodzi.
Jak easyCoexistence przechodzi kontrole Meta?
Jego aplikacja Meta ma jeden adres callbacku dla połączonych Page, a ten endpoint wykonuje obie kontrole sam. Odpowiada na GET tylko wtedy, gdy hub.mode to subscribe, a token weryfikacyjny się zgadza, i porównuje go w stałym czasie. W pozostałych przypadkach zwraca 403. Każdy POST czyta jako surowy tekst, przelicza X-Hub-Signature-256 swoim App Secret i odrzuca niezgodność kodem 401. Od razu odpowiada Meta, a zdarzenie obsługuje po odpowiedzi.
Jak easyCoexistence podpisuje to, co przekazuje?
Własnym podpisem, bo nagłówek Meta można sprawdzić tylko App Secret easyCoexistence i nie jest on przekazywany dalej. Każdy wpis dla połączonej Page z ustawionym endpointem jest wysyłany tam jako POST w JSON: {platform, account_id, external_id, entry}, z nagłówkiem X-EC-Signature w formie t=<unix>,v1=<hex>. Pole v1 to HMAC-SHA256 z znacznika czasu, kropki i surowego ciała, kluczowany sekretem podpisu tej Page:
- Sekret zaczyna się od whsec_ i jest pokazywany jednorazowo przez
set_social_webhook_destinationalbo PUT /channels/:id/webhook w Partner API. - Ponowne ustawienie adresu wystawia nowy sekret, a pusty adres (null) wyłącza przekazywanie.
- Każde przekazanie wysyłane jest raz, z czekaniem do 8 sekund, bez podążania za przekierowaniami, na adres HTTPS rozwiązujący się do publicznego IP.
- Kopia zdarzenia nie jest przechowywana, więc nie ma skąd ponowić.
Jak zweryfikować X-EC-Signature?
Rozdziel nagłówek na t i v1, odrzuć znacznik czasu starszy niż 5 minut, przelicz HMAC z t, kropki i surowego ciała sekretem podpisu Page i porównaj w stałym czasie. W Node.js, z ciałem zachowanym jako surowe bajty:
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
});Typowe błędy
- Owijanie hub.challenge w JSON lub cudzysłów. Treść odpowiedzi 200 musi być samą wartością challenge.
- Liczenie HMAC po parserze JSON. Parsowanie i ponowna serializacja zmieniają bajty, a Meta podpisuje payload z escape'owanym Unicode, więc haszuj surowe ciało.
- Wykonywanie pracy przed odpowiedzią. Messenger oczekuje 200 w ciągu 5 sekund, a godzina błędów wypisuje aplikację z Page.
- Sprawdzanie podpisu Meta na przekazanych zdarzeniach. Meta podpisuje App Secret easyCoexistence; przekazane zdarzenie niesie X-EC-Signature, sprawdzany sekretem podpisu Page.
Następnie przekazuje zdarzenia na Twój endpoint HTTPS, podpisane X-EC-Signature i sekretem tej Page. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, spadając w miarę dodawania połączeń, z pierwszymi 3 dniami bezpłatnie.
Najczęściej zadawane pytania
Skąd bierze się verify token?
Wybierasz go sam. To ciąg wpisany w polu Verify Token przy konfiguracji webhooków w App Dashboard albo verify_token wysłany do /{app-id}/subscriptions.
Czy mogę przetestować weryfikację przez curl?
Tak. Przewodnik Meta po Messengerze wysyła GET z hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED i hub.mode=subscribe, a działający endpoint odpowiada CHALLENGE_ACCEPTED.
Co się stanie, jeśli mój endpoint zawodzi przez godzinę?
Meta wysyła alert Webhooks Disabled i wypisuje aplikację z Page. Po naprawie endpointu zasubskrybuj Page ponownie przez subscribed_apps.
Czy potrzebuję własnej aplikacji Meta, żeby odbierać webhooki Page?
Nie w easyCoexistence. Meta dostarcza zdarzenia do jego aplikacji, a ta przekazuje zdarzenia każdej Page na endpoint, który ustawisz, podpisane X-EC-Signature.
Czytaj dalej
Połącz pierwszy kanał w dwie minuty.
Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.
- 3 dni za darmo
- Rezygnacja w każdej chwili
- Tylko oficjalne API
- Monitorowanie 24/7
Zweryfikowano w