Verificarea webhook-ului Facebook: hub.challenge și X-Hub-Signature-256
Facebook verifică un endpoint de webhook printr-un GET care conține hub.mode setat la subscribe, hub.verify_token și hub.challenge; endpoint-ul compară token-ul cu cel din App Dashboard și returnează valoarea hub.challenge în corp. Apoi, fiecare eveniment sosește ca POST semnat în X-Hub-Signature-256: sha256= urmat de HMAC-SHA256 al payload-ului, cu secretul aplicației drept cheie.
easyCoexistence gestionează partea Meta pentru fiecare pagină pe care o conectați: aplicația sa răspunde la hub.challenge, verifică X-Hub-Signature-256 și abonează pagina la feed-ul, mesajele și mențiunile, apoi transmite evenimentele către endpoint-ul dumneavoastră HTTPS, semnate cu X-EC-Signature și cu un secret pentru acea pagină.
În cererea de verificare Meta, hub.mode are întotdeauna valoarea subscribe; hub.challenge este un număr întreg de returnat.
Prefixul X-Hub-Signature-256, urmat de semnătura SHA256 pe care Meta o generează din payload și App Secret.
Cât de repede trebuie endpoint-ul webhook-ului Messenger să răspundă la fiecare notificare, cu 200 OK.
După câte livrări eșuate apar alerta Webhooks Disabled și dezabonarea aplicației de la pagină.
Cât timp reîncearcă Meta o notificare de pagină eșuată, cu frecvență tot mai mică, înainte să o elimine.
Ce conține cererea de verificare a Meta?
Un GET către URL-ul de callback, trimis ori de câte ori produsul Webhooks este configurat în App Dashboard sau este creat un abonament prin /{app-id}/subscriptions. Odată cu el vin trei parametri de interogare:
- hub.mode: întotdeauna subscribe.
- hub.challenge: un număr întreg pe care endpoint-ul trebuie să îl returneze.
- hub.
verify_token: șirul introdus în câmpul Verify Token din dashboard-ul aplicației. - PHP transformă punctele în liniuțe de subliniere, așa că le citește ca
hub_mode,hub_challengeșihub_verify_token.
Cum trebuie să răspundă endpoint-ul?
Cu un 200 al cărui corp este întreaga valoare hub.challenge, dar numai dacă hub.mode este subscribe și hub.verify_token corespunde; orice altceva primește un 403, ca în aplicația de exemplu a Meta. Dashboard-ul arată dacă endpoint-ul a trecut verificarea, iar /{app-id}/subscriptions răspunde cu success sau cu o eroare. Endpoint-ul are nevoie de HTTPS cu un certificat TLS sau SSL valid, deoarece certificatele autosemnate nu sunt acceptate.
Cum se calculează X-Hub-Signature-256?
Ca HMAC-SHA256 al payload-ului cererii, cu secretul aplicației drept cheie, scris în hexazecimal cu litere mici după sha256=. Ghidul Messenger al Meta adaugă că semnătura acoperă payload-ul cu Unicode escapat, astfel încât un șir precum äöå se numără ca \u00e4\u00f6\u00e5: calculați hash-ul corpului brut exact cum a fost primit, niciodată o copie decodată sau serializată din nou. Meta spune că validarea este opțională, dar o recomandă cu tărie.
Cum se verifică în cod?
Păstrați octeții bruți, calculați HMAC-ul, comparați în timp constant, apoi parsați. Funcția get_data din Flask returnează corpul neatins, adică exact ce a fost semnat; parsarea mai întâi și serializarea apoi ar schimba octeții. Un endpoint mic care răspunde la verificare și verifică fiecare 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", 200Ce așteaptă Meta după verificare?
Un 200 OK pentru fiecare notificare, în cel mult 5 secunde pentru evenimentele Messenger. Meta grupează până la 1.000 de actualizări pe livrare, fără să garanteze asta, și tratează eșecurile astfel:
- Notificările de pagină: reîncercate imediat, apoi de câteva ori cu frecvență tot mai mică, timp de 36 de ore, după care sunt eliminate.
- Notificările Messenger: reîncercate de câteva ori imediat; după 15 minute de eșecuri, o alertă ajunge la contul de dezvoltator.
- După o oră de eșecuri, urmează alerta Webhooks Disabled, iar aplicația este dezabonată de la pagină până când se abonează din nou.
- Reîncercările pot livra un eveniment de două ori și în altă ordine, așa că deduplicați și sortați mesajele după marcajul de timp.
- Notificările trecute nu mai pot fi interogate ulterior, așa că stocați ce vă trebuie pe măsură ce sosesc.
Cum trece easyCoexistence verificările Meta?
Aplicația sa Meta are un singur URL de callback pentru paginile pe care le conectează, iar acel endpoint face singur ambele verificări. Răspunde la GET numai dacă hub.mode este subscribe și token-ul de verificare corespunde, comparat în timp constant, și returnează 403 în caz contrar. Citește fiecare POST ca text brut, recalculează X-Hub-Signature-256 cu App Secret-ul său, refuză o nepotrivire cu 401 și răspunde imediat Meta, tratând evenimentul după răspuns.
Cum semnează easyCoexistence ce transmite?
Cu o semnătură proprie, deoarece antetul Meta poate fi verificat doar cu App Secret-ul easyCoexistence și nu este transmis mai departe. Fiecare intrare pentru o pagină conectată, cu endpoint setat, este trimisă acolo prin POST ca JSON, {platform, account_id, external_id, entry}, cu un antet X-EC-Signature de forma t=<unix>,v1=<hex>, unde v1 este HMAC-SHA256 al marcajului de timp, al unui punct și al corpului brut, cu cheia de semnare a acelei pagini:
- Secretul începe cu whsec_ și se afișează o singură dată, prin
set_social_webhook_destinationsau PUT /channels/:id/webhook din Partner API. - Setarea din nou a URL-ului emite un secret nou, iar un URL null dezactivează transmiterea.
- Fiecare transmitere se trimite o singură dată, așteptând până la 8 secunde, fără să urmeze redirecționări, către o adresă HTTPS care se rezolvă într-un IP public.
- Nu se păstrează nicio copie a evenimentului, deci nu există de unde să reîncerce.
Cum verificați X-EC-Signature?
Împărțiți antetul în t și v1, respingeți un marcaj de timp mai vechi de 5 minute, recalculați HMAC-ul peste t, un punct și corpul brut cu cheia de semnare a paginii, apoi comparați în timp constant. În Node.js, cu corpul păstrat ca octeți bruți:
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
});Greșeli frecvente
- Încadrarea lui hub.challenge în JSON sau ghilimele. Corpul răspunsului 200 trebuie să fie chiar valoarea hub.challenge.
- Calcularea HMAC-ului după un parser JSON. Parsarea și reserializarea schimbă octeții, iar Meta semnează payload-ul cu Unicode escapat, deci calculați hash-ul pe corpul brut.
- Efectuarea lucrului înainte de răspuns. Messenger așteaptă un 200 în 5 secunde, iar o oră de eșecuri dezabonează aplicația de la pagină.
- Verificarea semnăturii Meta pe evenimentele transmise. Meta semnează cu App Secret-ul easyCoexistence; un eveniment transmis poartă X-EC-Signature, verificat cu cheia de semnare a paginii.
US$ 9 până la US$ 0.75 pe conexiune pe lună, scăzând pe măsură ce adăugați conexiuni, cu primele 3 zile gratuite.
Întrebări frecvente
De unde vine token-ul de verificare?
Îl alegeți dumneavoastră. Este șirul introdus în câmpul Verify Token la configurarea webhook-urilor în App Dashboard, sau verify_token trimis către /{app-id}/subscriptions.
Pot testa verificarea cu curl?
Da. Ghidul Messenger al Meta trimite un GET cu hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED și hub.mode=subscribe, iar un endpoint funcțional răspunde cu CHALLENGE_ACCEPTED.
Ce se întâmplă dacă endpoint-ul meu eșuează timp de o oră?
Meta trimite o alertă Webhooks Disabled și dezabonează aplicația de la pagină. După ce reparați endpoint-ul, abonați din nou pagina prin subscribed_apps.
Am nevoie de propria mea aplicație Meta pentru a primi webhook-urile unei pagini?
Nu, cu easyCoexistence. Meta livrează către aplicația sa, care transmite evenimentele fiecărei pagini către endpoint-ul pe care îl setați, semnate cu X-EC-Signature.
Continuați să citiți
Conectați primul canal în două minute.
Fără recenzii de platformă de așteptat. Conectați WhatsApp, Instagram, TikTok sau alt canal, apoi cereți AI-ului să publice, să răspundă sau să raporteze și urmăriți-l cum lucrează.
- 3 zile gratuit
- Anulați oricând
- Doar API-uri oficiale
- Monitorizat 24/7
Verificat la