Verificarea webhook-ului Instagram: hub.challenge și X-Hub-Signature-256
Configurarea webhook-urilor Instagram presupune un endpoint HTTPS care răspunde la verificarea GET trimisă de Meta, ce conține hub.mode setat la subscribe, hub.verify_token și hub.challenge, verificând token-ul și returnând challenge-ul. Apoi Meta trimite prin POST evenimente JSON semnate în X-Hub-Signature-256 cu secretul aplicației, după ce aplicația se abonează la câmpuri și fiecare cont este abonat prin edge-ul subscribed_apps.
easyCoexistence se ocupă de partea Meta: aplicația sa trece verificarea, verifică X-Hub-Signature-256, abonează fiecare cont Instagram conectat la comentarii, mesaje și mențiuni, și redirecționează evenimentele către endpoint-ul dumneavoastră HTTPS, semnate cu X-EC-Signature și cu un secret pentru fiecare cont, urmărind fiecare conexiune permanent.
Valoarea hub.mode este întotdeauna prezentă în cererea de verificare a Meta.
Perioada în care Meta reîncearcă o notificare eșuată, cu frecvență tot mai mică, înainte să o elimine.
De livrări eșuate de mesaje înainte ca Meta să trimită o alertă contului de dezvoltator.
De livrări de mesaje eșuate înainte de alerta „Webhooks Disabled” și dezabonarea aplicației de la cont.
Modul aplicației pe care Meta îl cere înainte ca aplicația să primească notificări pentru conturile utilizatorilor.
Cum funcționează configurarea webhook-urilor Instagram?
În patru pași, în ordinea din ghidul Meta. Endpoint-ul trebuie să treacă verificarea înainte de a putea selecta orice câmp, aplicația trebuie să fie Live pentru a primi notificări pentru conturile utilizatorilor, iar verificarea afacerii este necesară pentru accesul în producție.
Ce conține cererea de verificare?
Un GET către URL-ul de callback, trimis ori de câte ori produsul Webhooks este configurat în App Dashboard. Când hub.verify_token coincide cu token-ul propriu al endpoint-ului, răspunsul este 200 cu valoarea hub.challenge drept întreg corpul; altfel, 403. Dashboard-ul arată dacă endpoint-ul a trecut verificarea.
- hub.mode: întotdeauna subscribe.
- hub.challenge: un număr întreg generat de Meta, pe care endpoint-ul trebuie să îl trimită înapoi.
- hub.
verify_token: șirul introdus în câmpul Verify Token din dashboard, pe care îl cunosc doar Meta și endpoint-ul. - În PHP, punctele din aceste nume devin caractere de subliniere, deci valorile sosesc ca
hub_mode,hub_challengeșihub_verify_token.
GET https://<YOUR_HOST>/webhooks/instagram
?hub.mode=subscribe
&hub.challenge=1158201444
&hub.verify_token=<YOUR_VERIFY_TOKEN>
HTTP/1.1 200 OK
Content-Type: text/plain
1158201444Unde se setează callback-ul și câmpurile?
În App Dashboard, la Instagram, API setup with Instagram login, Configure webhooks: URL-ul de callback și token-ul de verificare se introduc acolo, iar salvarea lor declanșează cererea de verificare. Produsul Instagram pornește abonat la comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral și messaging_seen, iar Manage permite dezabonarea de la oricare dintre ele. Butonul Test trimite o notificare de probă pentru un câmp selectat.
Cum se verifică X-Hub-Signature-256?
Meta semnează fiecare notificare de eveniment cu un HMAC-SHA256 al payload-ului, cheiat cu secretul aplicației, și o trimite în X-Hub-Signature-256 sub forma sha256= urmat de digestul hexazecimal. Receptorul calculează același HMAC peste corpul brut al cererii și îl compară cu antetul, în timp constant. Ghidul Meta pentru mesagerie arată că semnătura acoperă payload-ul cu Unicode escapat, deci calcularea hash-ului unui JSON decodat sau re-serializat dă un rezultat diferit.
import crypto from "node:crypto";
import express from "express";
const app = express();
const { VERIFY_TOKEN, APP_SECRET } = process.env;
// Verification request: send hub.challenge back when the token matches
app.get("/webhooks/instagram", (req, res) => {
const ok = req.query["hub.mode"] === "subscribe" &&
req.query["hub.verify_token"] === VERIFY_TOKEN;
if (!ok) return res.sendStatus(403);
res.status(200).type("text/plain").send(req.query["hub.challenge"]);
});
// Event notification: check the signature over the raw bytes
app.post("/webhooks/instagram", express.raw({ type: "application/json" }), (req, res) => {
const expected = Buffer.from(
"sha256=" + crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex")
);
const given = Buffer.from(req.get("X-Hub-Signature-256") ?? "");
if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
return res.sendStatus(401);
}
res.sendStatus(200); // answer first, work after
const body = JSON.parse(req.body.toString("utf8"));
// hand body.entry to a queue or background job
});
app.listen(3000);De ce o poate verifica doar secretul aplicației?
Pentru că semnătura este un HMAC cheiat cu acel secret. Fără el, nimeni nu poate calcula valoarea așteptată, iar cine deține o copie a unui payload nu poate falsifica unul, așa că verificarea aparține serverului care primește cererile Meta pentru aplicație. Meta cere ca secretele aplicației, token-urile de acces și credențialele client să nu apară în jurnale sau în cererile de suport. Un sistem care primește evenimente transmise de o altă aplicație nu poate verifica deloc semnătura Meta și se bazează, în schimb, pe semnătura proprie a acelei aplicații.
De ce are fiecare cont nevoie de propriul abonament?
Pentru că App Dashboard stabilește ce poate primi aplicația, dar notificările pentru un cont încep doar după ce și acel cont este abonat. Cu Instagram Login, trimiteți POST /<IG_ID>/subscribed_apps către graph.instagram.com, cu token-ul de acces Instagram User al contului și cu subscribed_fields, care listează câmpurile selectate pentru aplicație, separate prin virgulă. Un apel reușit returnează success setat la true.
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }Ce face Meta când livrările eșuează?
Reîncearcă, apoi renunță. Ghidul Meta cere un 200 OK pentru fiecare notificare și avertizează că grupările de până la 1.000 de actualizări nu sunt garantate. O actualizare eșuată este reîncercată imediat, apoi de câteva ori în plus, cu frecvență tot mai mică, timp de 36 de ore, iar după aceea este eliminată, astfel că același eveniment poate sosi de două ori. Evenimentele de mesagerie urmează regulile de livrare pentru mesagerie ale Meta, care acționează mai rapid:
- Se așteaptă un 200 OK în 5 secunde, iar o livrare eșuată primește câteva reîncercări imediate, așa că deduplicați după message mid.
- 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 webhook-urile contului până se reabonează.
- Mesajele trimise în timpul unei întreruperi pot sosi în dezordine, deci sortați-le după timestamp.
Ce trebuie verificat când nu sosește nimic?
Lista de verificare pentru depanare a Meta, care acoperă majoritatea endpoint-urilor tăcute, în această ordine:
- URL-ul de callback a trecut verificarea și este accesibil prin HTTPS, cu un certificat valid; certificatele autosemnate nu sunt acceptate.
- Aplicația a selectat câmpul și are nivelul de acces necesar, Advanced Access pentru comments și
live_comments. - Notificările sunt activate pentru cont prin
subscribed_apps, cu un token din aceeași configurare de login. - Contul respectă regulile câmpului: notificările pentru comentarii necesită media deținută de un cont public.
- Serverul returnează success înainte să înceapă lucrul lent.
De ce easyCoexistence semnează din nou evenimentele redirecționate?
Pentru că semnătura Meta nu poate fi transmisă mai departe. Aplicația easyCoexistence primește livrarea Meta, verifică X-Hub-Signature-256 cu propriul secret al aplicației, îi răspunde imediat lui Meta și trimite prin POST fiecare intrare pentru un cont conectat către endpoint-ul setat pentru acel cont, într-un corp nou care conține platform, account_id, external_id și entry. Antetul Meta nu este transmis mai departe și nu ar putea fi verificat fără acel secret, așa că fiecare redirecționare poartă Content-Type: application/json și X-EC-Signature, cheiat cu un secret care aparține doar acelui cont.
Cum verificați X-EC-Signature?
Antetul arată astfel: t=<unix>,v1=<hex>, unde v1 este HMAC-SHA256 hexazecimal al timestamp-ului, al unui punct și al corpului brut, cheiat cu secretul de semnare al contului. Recalculați-l peste octeții exact cum au fost primiți, comparați în timp constant și respingeți un timestamp mai vechi de 5 minute.
- Secretul începe cu whsec_ și este afișat o singură dată, de
set_social_webhook_destinationsau PUT /channels/:id/webhook, când se setează URL-ul. - Setarea din nou a URL-ului emite un secret nou, iar un URL null oprește redirecționarea.
- Fiecare eveniment este trimis o singură dată, cu așteptare de până la 8 secunde, fără a urma redirecționări, către o adresă HTTPS care se rezolvă la un IP public.
- Eliminarea conexiunii dezabonează contul de la webhook-urile Meta și șterge endpoint-ul și secretul acestuia.
import hashlib, hmac, time
def verify_ec_signature(raw_body: bytes, header: str, secret: str) -> bool:
"""Check X-EC-Signature on an event forwarded by easyCoexistence."""
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False # missing, malformed or older than 5 minutes
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), v1.encode())Greșeli frecvente
- Returnarea challenge-ului ca JSON sau între ghilimele. Meta așteaptă valoarea hub.challenge ca atare, drept corp, cu status 200.
- Calcularea HMAC pe un corp parsat. Un parser JSON elimină octeții exacți semnați de Meta, deci păstrați corpul brut pentru HMAC și parsați-l după aceea.
- Abonarea aplicației și uitarea contului. Până când POST /<IG_ID>/subscribed_apps reușește pentru un cont, nu sosesc notificări pentru el.
- Lăsarea unui endpoint să eșueze timp de o oră. Meta dezactivează webhook-urile de mesagerie și dezabonează aplicația de la cont, care trebuie apoi abonat din nou.
Activați-l cu set_social_webhook_destination sau cu Partner API. De la US$ 9 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
Ce este hub.challenge în webhook-urile Instagram?
Un număr întreg pe care Meta îl trimite în cererea GET de verificare. După ce verifică hub.verify_token, endpoint-ul îl returnează ca întreg corp al răspunsului, ceea ce dovedește că el controlează URL-ul.
De ce lipsesc hub.mode și hub.challenge în PHP?
PHP transformă punctele din numele parametrilor în caractere de subliniere, deci valorile de verificare ale Meta sosesc ca hub_mode, hub_challenge și hub_verify_token.
Cum reactivez webhook-urile Instagram după ce Meta le dezactivează?
Reparați endpoint-ul, apoi abonați contul din nou cu POST /<IG_ID>/subscribed_apps și aceleași câmpuri.
Funcționează un certificat autosemnat pentru endpoint-ul webhook Instagram?
Nu, Meta nu acceptă certificate autosemnate: URL-ul de callback trebuie să fie accesibil prin HTTPS, cu un certificat valid, primul punct din lista de verificare pentru depanare a Meta.
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