Prijavite seZapočnite besplatni probni period
easyCoexistence Zvanični API-ji

Verifikacija Instagram webhook-a: hub.challenge i X-Hub-Signature-256

Podešavanje Instagram webhook-ova zahteva HTTPS endpoint koji odgovara na Metin GET zahtev za verifikaciju. Taj zahtev sadrži hub.mode postavljen na subscribe, hub.verify_token i hub.challenge, a endpoint proverava token i vraća vrednost hub.challenge. Zatim Meta šalje JSON događaje potpisane u X-Hub-Signature-256 tajnim ključem aplikacije, kada aplikacija pretplati polja i svaki nalog se pretplati preko subscribed_apps edge-a.

easyCoexistence se brine o Metinoj strani: aplikacija prolazi verifikaciju, proverava X-Hub-Signature-256, pretplaćuje svaki povezani Instagram nalog na comments, messages i pominjanja i prosleđuje događaje vašem HTTPS endpoint-u potpisane sa X-EC-Signature i tajnim ključem za svaki nalog, uz neprekidno praćenje svake veze.

subscribe

Vrednost hub.mode uvek stiže u Metinom zahtevu za verifikaciju.

36 hours

Period u kojem Meta ponavlja neuspelo obaveštenje, sa sve manjom učestalošću, pre nego što ga odbaci.

15 minutes

Neuspelih isporuka poruka pre nego što Meta pošalje upozorenje na razvojni nalog.

1 hour

Neuspelih isporuka poruka pre upozorenja Webhooks Disabled i odjave aplikacije sa naloga.

Live

Režim aplikacije, Live, koji Meta zahteva pre nego što aplikacija primi obaveštenja za naloge svojih korisnika.

Kako funkcioniše podešavanje Instagram webhook-ova?

U četiri koraka, redom kojim ih daje Metin vodič. Endpoint mora proći verifikaciju pre nego što se bilo koje polje može izabrati, aplikacija mora biti u režimu Live da bi primala obaveštenja za naloge svojih korisnika, a za pristup u produkciji potrebna je verifikacija preduzeća.

1EndpointAn HTTPS URL with a valid certificate answers the verification GET
2App fieldsCallback URL, verify token and fields set in the App Dashboard
3Each accountPOST /<IG_ID>/subscribed_apps turns its notifications on
4TestA dashboard test, then a real event, reach the endpoint

Šta sadrži zahtev za verifikaciju?

GET zahtev ka URL-u za povratni poziv, koji se šalje kad god se proizvod Webhooks podesi u App Dashboard-u. Kada se hub.verify_token poklapa sa sopstvenim tokenom endpoint-a, odgovor je 200 sa vrednošću hub.challenge kao celim telom; u suprotnom 403. Kontrolna tabla prijavljuje da li je endpoint prošao proveru.

  • hub.mode: uvek subscribe.
  • hub.challenge: ceo broj koji Meta generiše, a endpoint ga mora vratiti.
  • hub.verify_token: niz znakova unet u polje Verify Token u kontrolnoj tabli, koji treba da znaju samo Meta i endpoint.
  • U PHP-u se tačke u ovim nazivima pretvaraju u donje crte, pa vrednosti stižu kao hub_mode, hub_challenge i hub_verify_token.
The verification request and its answer
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

1158201444

Gde se podešavaju povratni poziv i polja?

U App Dashboard-u, pod Instagram, API setup with Instagram login, Configure webhooks: URL za povratni poziv i verify token unose se tamo, a čuvanje pokreće zahtev za verifikaciju. Proizvod Instagram je na početku pretplaćen na comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral i messaging_seen, a Manage odjavljuje bilo koje od njih. Dugme Test šalje probno obaveštenje za izabrano polje.

Kako se proverava X-Hub-Signature-256?

Meta potpisuje svako obaveštenje HMAC-SHA256 nad payload-om, ključem koji je tajni ključ aplikacije, i šalje ga u X-Hub-Signature-256 kao sha256= i heksadecimalni digest. Primalac računa isti HMAC nad sirovim telom zahteva i poredi ga sa zaglavljem u konstantnom vremenu. Metin vodič za poruke navodi da potpis obuhvata payload sa escape-ovanim Unicode znacima, pa heširanje dekodiranog ili ponovo serijalizovanog JSON-a daje drugi rezultat.

Node.js: answering verification and checking X-Hub-Signature-256
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 samo tajni ključ aplikacije može da proveri potpis?

Zato što je potpis HMAC vrednost izračunata tajnim ključem aplikacije. Bez njega niko ne može da izračuna očekivanu vrednost, a niko ko ima kopiju payload-a ne može da ga falsifikuje, pa se provera mora obavljati na serveru koji prima Metine zahteve za aplikaciju. Meta traži da tajni ključevi aplikacije, access tokeni i kredencijali klijenta ostanu van logova i zahteva za podršku. Sistem koji prima događaje koje prosleđuje druga aplikacija ne može da proveri Metin potpis uopšte, nego se oslanja na sopstveni potpis te aplikacije.

Zašto svaki nalog treba sopstvenu pretplatu?

Zato što App Dashboard određuje šta aplikacija može da prima, ali obaveštenja za nalog počinju tek kada je i taj nalog pretplaćen. Uz Instagram Login, šaljete POST /<IG_ID>/subscribed_apps na graph.instagram.com sa Instagram User access tokenom naloga i subscribed_fields sa poljima izabranim za aplikaciju, odvojenim zarezima. Uspešan poziv vraća success postavljen na true.

Subscribing one account to comments and messages
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
  ?subscribed_fields=comments,messages
  &access_token=<INSTAGRAM_USER_ACCESS_TOKEN>

{ "success": true }

Šta Meta radi kada isporuke ne uspeju?

Ponovo pokušava, pa odustaje. Metin vodič traži 200 OK za svako obaveštenje i upozorava da grupisanje, do 1.000 ažuriranja, nije zagarantovano. Neuspelo ažuriranje se ponovo šalje odmah, pa još nekoliko puta sa sve manjom učestalošću tokom 36 sati, a potom se odbacuje, pa isti događaj može stići dvaput. Događaji poruka prate Metina pravila isporuke poruka, koja deluju brže:

  • Očekuje se 200 OK u roku od 5 sekundi, a neuspela isporuka dobija nekoliko odmah ponovljenih pokušaja, pa deduplikujte po mid vrednosti poruke.
  • Posle 15 minuta neuspeha, upozorenje stiže na razvojni nalog.
  • Posle sat vremena neuspeha sledi upozorenje Webhooks Disabled, a aplikacija se odjavljuje sa webhook-ova naloga dok se ponovo ne pretplati.
  • Poruke poslate tokom prekida mogu stići van redosleda, pa ih sortirajte po vremenskom žigu.

Šta proveriti kada ništa ne stiže?

Metina lista za rešavanje problema, koja pokriva većinu tihih endpoint-a, tim redom:

  • URL za povratni poziv je prošao proveru i dostupan je preko HTTPS-a sa važećim sertifikatom; samopotpisani nisu podržani.
  • Aplikacija je izabrala polje i ima nivo pristupa koji mu treba, Advanced Access za comments i live_comments.
  • Obaveštenja su uključena za nalog preko subscribed_apps, sa tokenom iz istog podešavanja prijave.
  • Nalog ispunjava pravila polja: obaveštenja o komentarima zahtevaju medijski sadržaj u vlasništvu javnog naloga.
  • Server vraća success pre nego što počne sporiji posao.

Zašto easyCoexistence ponovo potpisuje prosleđene događaje?

Zato što Metin potpis ne može da putuje dalje. Aplikacija easyCoexistence prima Metinu isporuku, proverava X-Hub-Signature-256 sopstvenim tajnim ključem aplikacije, odmah odgovara Metinu i šalje POST zahtev sa svakim unosom za povezani nalog na endpoint podešen za taj nalog, u novom telu sa platform, account_id, external_id i entry. Metino zaglavlje se ne prosleđuje i ne bi se moglo proveriti bez tog ključa, pa svaki prosleđeni zahtev nosi Content-Type: application/json i X-EC-Signature, potpisan ključem koji pripada tom jednom nalogu.

Kako se proverava X-EC-Signature?

Zaglavlje glasi t=<unix>,v1=<hex>, gde je v1 heksadecimalni HMAC-SHA256 vremenskog žiga, tačke i sirovog tela, ključem potpisa naloga. Ponovo ga izračunajte nad bajtovima tačno onako kako su primljeni, uporedite u konstantnom vremenu i odbacite vremenski žig stariji od 5 minuta.

  • Tajni ključ počinje sa whsec_ i prikazuje se jednom, pomoću set_social_webhook_destination ili PUT /channels/:id/webhook kada se postavi URL.
  • Ponovno postavljanje URL-a izdaje novi tajni ključ, a null URL isključuje prosleđivanje.
  • Svaki događaj se šalje jednom, uz čekanje do 8 sekundi, bez praćenja preusmeravanja, na HTTPS adresu koja se razrešava u javnu IP adresu.
  • Uklanjanje veze odjavljuje nalog sa Metinih webhook-ova i briše njegov endpoint i tajni ključ.
Python: checking X-EC-Signature
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())

Česte greške

  • Vraćanje challenge-a kao JSON-a ili pod navodnicima. Meta očekuje samu vrednost hub.challenge kao telo, sa statusom 200.
  • Heširanje parsiranog tela. JSON parser odbacuje tačne bajtove koje je Meta potpisala, pa sirovo telo čuvajte za HMAC i parsirajte ga posle.
  • Pretplata aplikacije, a zaboravljen nalog. Dok POST /<IG_ID>/subscribed_apps ne uspe za nalog, obaveštenja za njega ne stižu.
  • Dozvoliti da endpoint otkazuje ceo sat. Meta isključuje webhook-ove za poruke i odjavljuje aplikaciju sa naloga, koji se mora ponovo pretplatiti.
Ovo radite uz EasyCoexistence

Uključite ga pomoću set_social_webhook_destination ili Partner API-ja. Od US$ 9 do US$ 0,75 po vezi mesečno, sa padom kako dodajete veze, prvih 3 dana besplatno.

Često postavljana pitanja

Šta je hub.challenge u Instagram webhook-ovima?

Ceo broj koji Meta šalje u GET zahtevu za verifikaciju. Nakon provere hub.verify_token, endpoint ga vraća kao telo odgovora, čime dokazuje da kontroliše URL.

Zašto u PHP-u nedostaju hub.mode i hub.challenge?

PHP pretvara tačke u nazivima parametara u donje crte, pa Metine vrednosti verifikacije stižu kao hub_mode, hub_challenge i hub_verify_token.

Kako ponovo uključiti Instagram webhook-ove posle isključenja?

Popravite endpoint, pa ponovo pretplatite nalog preko POST /<IG_ID>/subscribed_apps sa istim poljima.

Da li samopotpisani sertifikat radi za Instagram webhook endpoint?

Ne, Meta ne podržava samopotpisane sertifikate: URL za povratni poziv mora biti dostupan preko HTTPS-a sa važećim sertifikatom, što je prva stavka na Metinoj listi za rešavanje problema.

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