Verifikacija Facebook webhooka: hub.challenge i X-Hub-Signature-256
Facebook proverava webhook endpoint GET zahtevom koji nosi hub.mode postavljen na subscribe, hub.verify_token i hub.challenge. Endpoint proverava token u odnosu na onaj iz kontrolne table aplikacije i kao telo odgovora vraća vrednost hub.challenge. Svaki događaj zatim stiže kao POST potpisan u zaglavlju X-Hub-Signature-256: sha256= iza kojeg sledi HMAC-SHA256 od payloada, ključen App Secret-om.
easyCoexistence preuzima Metinu stranu za svaku stranicu koju povežete: njegova aplikacija odgovara na hub.challenge, proverava X-Hub-Signature-256 i pretplaćuje stranicu na feed, poruke i mention, zatim prosleđuje događaje vašem HTTPS endpointu potpisane sa X-EC-Signature i tajnim ključem te stranice.
Vrednost koju hub.mode uvek nosi u Metinom zahtevu za verifikaciju; hub.challenge je ceo broj koji treba vratiti.
Prefiks zaglavlja X-Hub-Signature-256, nakon kojeg sledi SHA256 potpis koji Meta generiše iz payloada i App Secret-a.
Koliko brzo webhook endpoint za Messenger treba da odgovori na svaku notifikaciju kodom 200 OK.
Neuspelih isporuka pre upozorenja Webhooks Disabled i odjave aplikacije sa stranice.
Koliko dugo Meta ponavlja neuspelu notifikaciju stranice, sa sve manjom učestalošću, pre nego što je odbaci.
Šta sadrži Metin zahtev za verifikaciju?
GET zahtev na callback URL, poslat kad god je Webhooks proizvod podešen u kontrolnoj tabli aplikacije ili kad se pretplata kreira preko /{app-id}/subscriptions. Uz njega stižu tri parametra upita:
- hub.mode: uvek subscribe.
- hub.challenge: ceo broj koji endpoint mora da vrati.
- hub.
verify_token: string unet u polje Verify Token u kontrolnoj tabli. - PHP tačke pretvara u donje crte, pa ih čita kao
hub_mode,hub_challengeihub_verify_token.
Kako endpoint treba da odgovori?
Kodom 200 čije je celo telo vrednost hub.challenge, ali samo kada je hub.mode jednak subscribe i hub.verify_token se poklapa; sve ostalo dobija 403, kao u Metinoj aplikaciji sa primerom. Kontrolna tabla prijavljuje da li je endpoint prošao, a /{app-id}/subscriptions odgovara sa uspehom ili greškom. Endpoint mora da radi preko HTTPS-a sa važećim TLS ili SSL sertifikatom, jer se samopotpisani sertifikati ne podržavaju.
Kako se računa X-Hub-Signature-256?
Kao HMAC-SHA256 od payloada zahteva, ključen App Secret-om aplikacije, zapisan malim heksadecimalnim slovima iza sha256=. Metin vodič za Messenger dodaje da potpis obuhvata payload sa Unicode escape-ovanim karakterima, pa se niz kao äöå računa kao \u00e4\u00f6\u00e5: heširajte sirovo telo tačno onako kako je primljeno, nikad dekodiranu ili ponovo serijalizovanu kopiju. Meta kaže da je validacija opciona, ali je snažno preporučuje.
Kako se to proverava u kodu?
Zadržite sirove bajtove, izračunajte HMAC, uporedite u konstantnom vremenu, pa tek onda parsirajte. Flask-ov get_data vraća telo netaknuto, a upravo nad njim je potpis izračunat; prvo parsiranje pa ponovna serijalizacija promenila bi bajtove. Mali endpoint koji odgovara na verifikaciju i proverava svaki 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", 200Šta Meta očekuje posle verifikacije?
Kod 200 OK za svaku notifikaciju, u roku od 5 sekundi za Messenger događaje. Meta grupiše do 1.000 ažuriranja po isporuci bez garancije i postupa sa greškama ovako:
- Notifikacije stranice: ponovo se šalju odmah, zatim još nekoliko puta sa sve manjom učestalošću tokom 36 sati, pa se odbacuju.
- Messenger notifikacije: nekoliko puta ponovo odmah; posle 15 minuta grešaka, upozorenje stiže na developerski nalog.
- Posle sat vremena grešaka stiže upozorenje Webhooks Disabled, a aplikacija se odjavljuje sa stranice dok se ponovo ne pretplati.
- Ponovni pokušaji mogu isporučiti događaj dva puta i u pogrešnom redosledu, pa deduplikujte i sortirajte poruke po vremenskoj oznaci.
- Prošle notifikacije se naknadno ne mogu dohvatiti, pa sačuvajte što vam treba čim stigne.
Kako easyCoexistence prolazi Metine provere?
Njegova Meta aplikacija ima jedan callback URL za stranice koje povezuje, a taj endpoint sam obavlja obe provere. Na GET odgovara samo kada je hub.mode jednak subscribe i verify token se poklapa, uporedeno u konstantnom vremenu, a inače vraća 403. Svaki POST čita kao sirov tekst, ponovo računa X-Hub-Signature-256 sopstvenim App Secret-om, odbija neslaganje kodom 401 i odmah odgovara Meti, a događaj obrađuje posle odgovora.
Kako easyCoexistence potpisuje ono što prosleđuje?
Sopstvenim potpisom, jer se Metino zaglavlje može proveriti samo App Secret-om easyCoexistence aplikacije i ne prosleđuje se dalje. Svaki unos za povezanu stranicu sa postavljenim endpointom šalje se POST-om kao JSON, {platform, account_id, external_id, entry}, uz zaglavlje X-EC-Signature u obliku t=<unix>,v1=<hex>. Pri čemu je v1 HMAC-SHA256 od vremenske oznake, tačke i sirovog tela, ključen tajnim ključem za potpisivanje te stranice:
- Tajni ključ počinje sa whsec_ i prikazuje se jednom, preko
set_social_webhook_destinationili PUT /channels/:id/webhook na Partner API-ju. - Ponovno postavljanje URL-a izdaje novi ključ, a URL null isključuje prosleđivanje.
- Svako prosleđivanje šalje se jednom, sa čekanjem do 8 sekundi, bez praćenja preusmeravanja, na HTTPS adresu koja se razrešava u javnu IP adresu.
- Kopija događaja se ne čuva, pa nema šta da se ponovi.
Kako se proverava X-EC-Signature?
Razdvojite zaglavlje na t i v1, odbacite vremensku oznaku stariju od 5 minuta, ponovo izračunajte HMAC nad t, tačkom i sirovim telom tajnim ključem stranice, pa uporedite u konstantnom vremenu. U Node.js-u, uz telo zadržano kao sirovi bajtovi:
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
});Česte greške
- Omotavanje hub.challenge-a u JSON ili navodnike. Telo odgovora sa kodom 200 mora biti sama vrednost hub.challenge-a.
- Računanje HMAC-a posle JSON parsera. Parsiranje i ponovna serijalizacija menjaju bajtove, a Meta potpisuje payload sa Unicode escape-ovanjem, pa hešujte sirovo telo.
- Obavljanje posla pre odgovora. Messenger očekuje 200 u roku od 5 sekundi, a sat vremena grešaka odjavljuje aplikaciju sa stranice.
- Provera Metinog potpisa na prosleđenim događajima. Meta potpisuje App Secret-om easyCoexistence; prosleđeni događaj nosi X-EC-Signature, koji se proverava tajnim ključem za potpisivanje stranice.
Od US$ 9 do US$ 0.75 po vezi mesečno, sa padom kako dodajete veze, uz besplatni probni period od 3 dana.
Često postavljana pitanja
Odakle dolazi verify token?
Birate ga sami. To je string unet u polje Verify Token pri podešavanju webhooka u kontrolnoj tabli aplikacije, ili verify_token poslat na /{app-id}/subscriptions.
Mogu li da testiram verifikaciju pomoću curl-a?
Mogu. Metin vodič za Messenger šalje GET sa hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED i hub.mode=subscribe, a ispravan endpoint odgovara sa CHALLENGE_ACCEPTED.
Šta se dešava ako moj endpoint ne radi sat vremena?
Meta šalje upozorenje Webhooks Disabled i odjavljuje aplikaciju sa stranice. Kad popravite endpoint, ponovo pretplatite stranicu preko subscribed_apps.
Treba li mi sopstvena Meta aplikacija da primam webhook-ove stranice?
Ne, uz easyCoexistence. Meta isporučuje svojoj aplikaciji, koja prosleđuje događaje svake stranice endpointu koji postavite, potpisane sa X-EC-Signature.
Nastavite sa čitanjem
Povežite prvi kanal za dva minuta.
Bez čekanja na odobrenja platformi. Povežite WhatsApp, Instagram, TikTok ili drugi kanal, zatim zamolite svoj AI da objavi, odgovori ili napravi izveštaj, i gledajte kako radi.
- 3 dana besplatno
- Otkažite bilo kada
- Samo zvanični API-ji
- Nadzor 24/7
Provereno na