Provjera Instagram webhooka: hub.challenge i X-Hub-Signature-256
Za postavljanje Instagram webhookova potreban je HTTPS endpoint koji odgovara na Metin verifikacijski GET zahtjev. On sadrži hub.mode postavljen na subscribe, hub.verify_token i hub.challenge. Endpoint provjerava token i vraća challenge. Meta zatim šalje JSON događaje potpisane u X-Hub-Signature-256 tajnim ključem aplikacije, nakon što aplikacija pretplati polja i svaki račun pretplati putem subscribed_apps edgea.
easyCoexistence preuzima Metinu stranu: njegova aplikacija prolazi verifikaciju, provjerava X-Hub-Signature-256, pretplaćuje svaki povezani Instagram račun na comments, messages i mentions te proslijeđuje događaje na vaš HTTPS endpoint potpisane s X-EC-Signature i ključem za svaki račun, uz neprekidni nadzor svake veze.
Vrijednost hub.mode uvijek je prisutna u Metinom zahtjevu za verifikaciju.
Razdoblje tijekom kojega Meta ponovno šalje neuspjelu obavijest, sve rjeđe, prije nego je odbaci.
Broj neuspjelih isporuka poruka prije nego Meta pošalje upozorenje na developerski račun.
Broj neuspjelih isporuka poruka prije upozorenja Webhooks Disabled i odjave aplikacije s računa.
Način rada aplikacije koji Meta zahtijeva prije nego aplikacija primi obavijesti za račune svojih korisnika.
Kako funkcionira postavljanje Instagram webhookova?
U četiri koraka, redoslijedom kojim ih daje Metin vodič. Endpoint mora proći verifikaciju prije nego se može odabrati ijedno polje, aplikacija mora biti u načinu rada Live da bi primala obavijesti za račune svojih korisnika, a za pristup produkciji potrebna je verifikacija tvrtke.
Što sadrži zahtjev za verifikaciju?
GET zahtjev na callback URL, poslan svaki put kad je proizvod Webhooks konfiguriran u App Dashboardu. Kad se hub.verify_token podudara s vlastitim tokenom endpointa, odgovor je 200 s vrijednošću hub.challenge kao cijelim tijelom odgovora; inače 403. Nadzorna ploča javlja je li endpoint prošao provjeru.
- hub.mode: uvijek subscribe.
- hub.challenge: cijeli broj koji generira Meta, a endpoint ga mora vratiti.
- hub.
verify_token: niz unesen u polje Verify Token na nadzornoj ploči, koji znaju samo Meta i endpoint. - U PHP-u se točke u tim nazivima pretvaraju u donje crte, pa vrijednosti stižu kao
hub_mode,hub_challengeihub_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
1158201444Gdje se postavljaju callback i polja?
U App Dashboardu, pod Instagram, API setup with Instagram login, Configure webhooks: callback URL i verify token unose se ovdje, a spremanje pokreće zahtjev za verifikaciju. Proizvod Instagram započinje pretplaćen na comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral i messaging_seen, a Manage odjavljuje od bilo kojeg od njih. Gumb Test šalje primjer obavijesti za odabrano polje.
Kako se provjerava X-Hub-Signature-256?
Meta potpisuje svaku obavijest o događaju HMAC-SHA256 hashom payloada, s tajnim ključem aplikacije, i šalje ga u X-Hub-Signature-256 kao sha256= nakon kojeg slijedi heksadecimalni sažetak. Primatelj izračunava isti HMAC nad neobrađenim tijelom zahtjeva i uspoređuje ga s zaglavljem u konstantnom vremenu. Metin vodič za poruke navodi da potpis pokriva payload s Unicodeom zapisanim u escape obliku, pa hashiranje dekodiranog ili ponovno serijaliziranog JSON-a daje drugačiji rezultat.
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);Zašto to može provjeriti samo tajni ključ aplikacije?
Zato što je potpis HMAC s tim ključem. Bez njega nitko ne može izračunati očekivanu vrijednost, a nitko tko ima kopiju payloada ne može ga krivotvoriti, pa se provjera mora izvoditi na poslužitelju koji prima Metine zahtjeve za aplikaciju. Meta traži da tajni ključevi aplikacije, pristupni tokeni i klijentske vjerodajnice ostanu izvan logova i zahtjeva za podršku. Sustav koji prima događaje koje je proslijedila druga aplikacija ne može provjeriti Metin potpis, nego se oslanja na potpis te aplikacije.
Zašto svaki račun treba zasebnu pretplatu?
Zato što App Dashboard određuje što aplikacija može primati, ali obavijesti za račun počinju tek kad je i taj račun pretplaćen. Uz Instagram Login, pošaljite POST /<IG_ID>/subscribed_apps na graph.instagram.com s Instagram User pristupnim tokenom računa i subscribed_fields koji navodi polja odabrana za aplikaciju, odvojena zarezima. Uspješan poziv vraća success postavljen na true.
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }Što Meta radi kad isporuke ne uspiju?
Ponavlja pokušaj, pa odustaje. Metin vodič traži 200 OK za svaku obavijest i upozorava da grupiranje, do 1.000 ažuriranja, nije zajamčeno. Neuspjelo ažuriranje ponovno se šalje odmah, zatim još nekoliko puta sa sve rjeđom učestalošću kroz 36 sati, a nakon toga se odbacuje, pa isti događaj može stići dvaput. Događaji za poruke slijede Metinova pravila isporuke poruka, koja djeluju brže:
- Očekuje se 200 OK u roku od 5 sekundi, a neuspjela isporuka dobiva nekoliko trenutnih ponovnih pokušaja, pa deduplicirajte prema mid vrijednosti poruke.
- Nakon 15 minuta neuspjeha, upozorenje ide na developerski račun.
- Nakon sat vremena neuspjeha slijedi upozorenje Webhooks Disabled, a aplikacija se odjavljuje s webhookova računa dok se ponovno ne pretplati.
- Poruke poslane tijekom prekida mogu stići izvan redoslijeda, pa ih sortirajte po vremenskoj oznaci.
Što provjeriti kad ništa ne stiže?
Metin kontrolni popis za rješavanje problema, koji pokriva većinu nemih endpointa, tim redoslijedom:
- Callback URL je prošao provjeru i dostupan je preko HTTPS-a s valjanim certifikatom; certifikati s vlastitim potpisom nisu podržani.
- Aplikacija je odabrala polje i ima potrebnu razinu pristupa, Advanced Access za comments i
live_comments. - Obavijesti su uključene za račun putem
subscribed_apps, s tokenom iz istog prijavnog postavljanja. - Račun zadovoljava pravila polja: obavijesti o komentarima zahtijevaju medij u vlasništvu javnog računa.
- Poslužitelj vraća success prije nego počne sporiji posao.
Zašto easyCoexistence ponovno potpisuje proslijeđene događaje?
Zato što Metin potpis ne može putovati dalje. Aplikacija easyCoexistence prima Metinu isporuku, provjerava X-Hub-Signature-256 svojim tajnim ključem aplikacije, odmah odgovara Meti i šalje svaki unos za povezani račun na endpoint postavljen za taj račun, u novom tijelu s poljima platform, account_id, external_id i entry. Metino zaglavlje se ne prosljeđuje i ne bi se moglo provjeriti bez tog ključa, pa svaki proslijeđeni zahtjev nosi Content-Type: application/json i X-EC-Signature, potpisan ključem koji pripada samo tom računu.
Kako se provjerava X-EC-Signature?
Zaglavlje glasi t=<unix>,v1=<hex>, gdje je v1 heksadecimalni HMAC-SHA256 vremenske oznake, točke i neobrađenog tijela, s tajnim ključem za potpisivanje računa. Ponovno ga izračunajte nad bajtovima točno onako kako su primljeni, usporedite u konstantnom vremenu i odbacite vremensku oznaku stariju od 5 minuta.
- Tajni ključ počinje s whsec_ i prikazuje se jednom, pri postavljanju URL-a, putem
set_social_webhook_destinationili PUT /channels/:id/webhook. - Ponovno postavljanje URL-a izdaje novi ključ, a null URL isključuje proslijeđivanje.
- Svaki događaj šalje se jednom, uz čekanje do 8 sekundi, bez praćenja preusmjeravanja, na HTTPS adresu koja se razrješava u javnu IP adresu.
- Uklanjanje veze odjavljuje račun s Metinih webhookova i briše njegov endpoint i tajni ključ.
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())Uobičajene pogreške
- Vraćanje vrijednosti hub.challenge kao JSON-a ili u navodnicima. Meta očekuje samu vrijednost hub.challenge kao tijelo odgovora, sa statusom 200.
- Hashiranje parsiranog tijela. Parser JSON tijela odbacuje točne bajtove koje je Meta potpisao, pa neobrađeno tijelo čuvajte za HMAC, a parsirajte ga naknadno.
- Pretplata aplikacije uz zaboravljen račun. Dok POST /<IG_ID>/subscribed_apps za račun ne uspije, za njega ne stiže nijedna obavijest.
- Dopuštanje da endpoint pada cijeli sat. Meta isključuje webhookove za poruke i odjavljuje aplikaciju s računa, koji se tada mora ponovno pretplatiti.
Uključite ga pomoću set_social_webhook_destination ili Partner API-ja. US$ 9 do US$ 0,75 po vezi mjesečno, uz pad kako dodajete veze, s prvih 3 dana besplatno.
Često postavljana pitanja
Što je hub.challenge u Instagram webhookovima?
Cijeli broj koji Meta šalje u svom GET zahtjevu za verifikaciju. Nakon provjere hub.verify_token endpoint ga vraća kao tijelo odgovora, čime dokazuje da kontrolira URL.
Zašto hub.mode i hub.challenge nedostaju u PHP-u?
PHP pretvara točke u nazivima parametara u donje crte, pa vrijednosti verifikacije stižu kao hub_mode, hub_challenge i hub_verify_token.
Kako ponovno uključiti Instagram webhookove nakon što ih Meta isključi?
Popravite endpoint, zatim ponovno pretplatite račun pomoću POST /<IG_ID>/subscribed_apps i istih polja.
Radi li certifikat s vlastitim potpisom za Instagram webhook endpoint?
Ne, Meta ne podržava certifikate s vlastitim potpisom: callback URL mora biti dostupan preko HTTPS-a s valjanim certifikatom, što je prva stavka Metinog kontrolnog popisa za rješavanje problema.
Nastavite čitati
Povežite svoj prvi kanal u dvije minute.
Bez čekanja na provjere platformi. Povežite WhatsApp, Instagram, TikTok ili drugi kanal, zatim zamolite svoju umjetnu inteligenciju da objavi, odgovori ili izradi izvješće i gledajte kako radi.
- 3 dana besplatno
- Otkažite bilo kada
- Samo službeni API-ji
- Nadzor 24/7
Provjereno na