Instagram-webhookin vahvistus: hub.challenge ja X-Hub-Signature-256
Instagram-webhookin käyttöönotto edellyttää HTTPS-päätepistettä, joka vastaa Metan vahvistuspyyntöön. Pyynnössä ovat hub.mode, jonka arvo on subscribe, hub.verify_token ja hub.challenge. Päätepiste tarkistaa tunnuksen ja palauttaa haasteen arvon. Tämän jälkeen Meta lähettää JSON-tapahtumia, jotka on allekirjoitettu X-Hub-Signature-256-otsikolla sovelluksen salaisuudella, kun sovellus on tilannut kentät ja jokainen tili on tilattu subscribed_apps-reunan kautta.
easyCoexistence hoitaa Metan puolen: sen sovellus läpäisee vahvistuksen, tarkistaa X-Hub-Signature-256-otsikon ja tilaa jokaisen yhdistetyn Instagram-tilin kommentteihin, viesteihin ja maininnoihin.
Arvo hub.mode on aina mukana Metan vahvistuspyynnössä.
Ajanjakso, jonka aikana Meta yrittää epäonnistunutta ilmoitusta uudelleen yhä harvemmin ennen sen hylkäämistä.
Epäonnistuneiden viestitoimitusten määrä, jonka jälkeen Meta lähettää hälytyksen kehittäjätilille.
Epäonnistuvien viestitoimitusten määrä, jonka jälkeen tulee Webhooks Disabled -hälytys ja sovellus peruu tilin tilauksen.
Sovellustila, jonka Meta vaatii, ennen kuin sovellus saa ilmoituksia käyttäjiensä tileiltä.
Miten Instagram-webhookien käyttöönotto toimii?
Neljässä vaiheessa, siinä järjestyksessä kuin Metan opas ne antaa. Päätepisteen on läpäistävä vahvistus ennen kuin mitään kenttää voi valita. Sovelluksen on oltava Live, jotta se voi vastaanottaa ilmoituksia käyttäjiensä tileiltä, ja tuotantokäyttöön vaaditaan yritystodennus.
Mitä vahvistuspyyntö sisältää?
GET-pyyntö takaisinkutsu-URL-osoitteeseen, joka lähetetään aina, kun Webhooks-tuote on määritetty App Dashboardissa. Jos hub.verify_token vastaa päätepisteen omaa tunnusta, vastaus on 200 ja koko runkona hub.challenge-arvo. Muuten vastaus on 403. Hallintapaneeli näyttää, onko päätepiste läpäissyt tarkistuksen.
- hub.mode: aina subscribe.
- hub.challenge: Metan generoima kokonaisluku, joka päätepisteen on palautettava.
- hub.
verify_token: merkkijono, joka syötetään App Dashboardin Verify Token -kenttään ja jonka vain Meta ja päätepiste tuntevat. - PHP:ssa näiden nimien pisteet muuttuvat alaviivoiksi, joten arvot saapuvat nimillä
hub_mode,hub_challengejahub_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
1158201444Mihin takaisinkutsu ja kentät asetetaan?
App Dashboardissa kohdassa Instagram, API setup with Instagram login, Configure webhooks. Takaisinkutsu-URL ja vahvistustunnus syötetään sinne, ja tallentaminen käynnistää vahvistuspyynnön. Instagram-tuote on oletuksena tilattu kenttiin comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral ja messaging_seen. Manage peruu tilauksen mistä tahansa niistä. Test-painike lähettää valitulle kentälle näytteen ilmoituksesta.
Miten X-Hub-Signature-256 tarkistetaan?
Meta allekirjoittaa jokaisen tapahtumailmoituksen HMAC-SHA256:lla, jonka avaimena on sovelluksen salaisuus. Allekirjoitus lähetetään X-Hub-Signature-256-otsikossa muodossa sha256= ja sen perässä heksadesimaalinen tiiviste. Vastaanottaja laskee saman HMAC:n raakaan pyynnön runkoon ja vertaa sitä otsikkoon vakioajassa. Metan viestiopas huomauttaa, että allekirjoitus kattaa hyötykuorman Unicode-merkit escapettuina, joten dekoodatun tai uudelleen sarjoitetun JSON:n tiivistäminen antaa eri tuloksen.
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);Miksi vain sovelluksen salaisuus voi tarkistaa sen?
Koska allekirjoitus on HMAC, jonka avain on tämä salaisuus. Ilman sitä kukaan ei voi laskea odotettua arvoa, eikä kopion perusteella voi väärentää tapahtumaa. Tarkistus kuuluu siksi sille palvelimelle, joka vastaanottaa sovelluksen Metalta tulevat pyynnöt. Meta pyytää, että sovelluksen salaisuudet, käyttöoikeustunnukset ja asiakastunnukset pidetään poissa lokeista ja tukipyynnöistä. Järjestelmä, joka vastaanottaa toisen sovelluksen välittämiä tapahtumia, ei voi tarkistaa Metan allekirjoitusta lainkaan, vaan luottaa sen sijaan tuon sovelluksen omaan allekirjoitukseen.
Miksi jokainen tili tarvitsee oman tilauksen?
Koska App Dashboard määrittää, mitä sovellus voi vastaanottaa, mutta ilmoitukset tililtä alkavat vasta, kun myös tili on tilattu. Instagram-kirjautumisella lähetetään POST /<IG_ID>/subscribed_apps osoitteeseen graph.instagram.com tilin Instagram User access token -tunnuksella ja subscribed_fields-kentällä, johon luetellaan sovellukselle valitut kentät pilkulla erotettuina. Onnistunut kutsu palauttaa success-arvon true.
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }Mitä Meta tekee, kun toimitukset epäonnistuvat?
Se yrittää uudelleen ja luovuttaa sitten. Metan opas pyytää vastaamaan jokaiseen ilmoitukseen 200 OK, ja varoittaa, että erien, jopa 1 000 päivityksen, toimitusta ei taata. Epäonnistunut päivitys yritetään heti uudelleen, sen jälkeen muutaman kerran yhä harvemmin 36 tunnin kuluessa ja lopuksi hylätään. Sama tapahtuma voi siis saapua kahdesti. Viestitapahtumiin sovelletaan Metan viestitoimitussääntöjä, jotka toimivat nopeammin:
- 200 OK odotetaan 5 sekunnin kuluessa, ja epäonnistunut toimitus saa muutaman välittömän uusintayrityksen, joten deduplikoi viestin mid-tunnisteen perusteella.
- 15 minuutin epäonnistumisten jälkeen hälytys menee kehittäjätilille.
- Tunnin epäonnistumisten jälkeen seuraa Webhooks Disabled -hälytys, ja sovellus peruu tilin webhookien tilauksen, kunnes se tilaa ne uudelleen.
- Katkon aikana lähetetyt viestit voivat saapua väärässä järjestyksessä, joten lajittele ne aikaleiman mukaan.
Mitä kannattaa tarkistaa, kun mitään ei saavu?
Metan vianmääritysluettelo kattaa useimmat hiljaiset päätepisteet. Tarkista tässä järjestyksessä:
- Takaisinkutsu-URL läpäisi tarkistuksen ja on tavoitettavissa HTTPS:n kautta voimassa olevalla varmenteella. Itse allekirjoitettuja varmenteita ei tueta.
- Sovellus valitsi kentän ja sillä on tarvittava käyttötaso, Advanced Access kentille comments ja
live_comments. - Ilmoitukset on otettu käyttöön tilille
subscribed_apps-kutsun kautta, tunnuksella samasta kirjautumisesta. - Tili täyttää kentän säännöt: kommenttien ilmoitukset vaativat median, joka kuuluu julkiselle tilille.
- Palvelin palauttaa success-vastauksen ennen kuin aloittaa hitaan työn.
Miksi easyCoexistence allekirjoittaa välitetyt tapahtumat uudelleen?
Koska Metan allekirjoitus ei voi kulkea mukana. easyCoexistencen sovellus vastaanottaa Metan toimituksen, tarkistaa X-Hub-Signature-256-otsikon omalla sovelluksen salaisuudellaan ja vastaa Metalle heti. Sen jälkeen se lähettää jokaisen yhdistetyn tilin merkinnän sille tilille asetettuun päätepisteeseen uuden rungon sisällä, jossa ovat platform, account_id, external_id ja entry. Metan otsikkoa ei välitetä eteenpäin, eikä sitä voisi tarkistaa ilman tuota salaisuutta. Jokainen välitys kulkee siksi mukana otsikoilla Content-Type: application/json ja X-EC-Signature, joka on allekirjoitettu yhden tilin omalla salaisuudella.
Miten X-EC-Signature tarkistetaan?
Otsikko on muotoa t=<unix>,v1=<hex>. Tässä v1 on aikaleiman, pisteen ja raakan rungon heksadesimaalinen HMAC-SHA256, jonka avaimena on tilin allekirjoitussalaisuus. Laske se uudelleen tavuille täsmälleen sellaisina kuin ne vastaanotettiin, vertaa vakioajassa ja hylkää aikaleima, joka on yli 5 minuuttia vanha.
- Salaisuus alkaa etuliitteellä whsec_ ja näytetään kerran kutsulla
set_social_webhook_destinationtai PUT /channels/:id/webhook, kun URL asetetaan. - URL:n asettaminen uudelleen luo uuden salaisuuden, ja tyhjä (null) URL lopettaa välityksen.
- Jokainen tapahtuma lähetetään kerran. Odotusaika on enintään 8 sekuntia, uudelleenohjauksia ei seurata, ja osoitteen on oltava HTTPS-osoite, joka ratkeaa julkiseksi IP-osoitteeksi.
- Yhteyden poistaminen peruu tilin Metan webhookien tilauksen ja tyhjentää sen päätepisteen ja salaisuuden.
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())Yleiset virheet
- Haasteen palauttaminen JSON-muodossa tai lainausmerkeissä. Meta odottaa hub.challenge-arvon sellaisenaan rungoksi 200-tilalla.
- Jäsennetyn rungon tiivistäminen. JSON-jäsennin hylkää tarkat tavut, jotka Meta allekirjoitti, joten säilytä raaka runko HMAC:a varten ja jäsennä se vasta sen jälkeen.
- Sovelluksen tilaaminen mutta tilin unohtaminen. Ennen kuin POST /<IG_ID>/subscribed_apps onnistuu tilille, sille ei saavu ilmoituksia.
- Päätepisteen antaminen epäonnistua tunnin ajan. Meta poistaa viestien webhookit käytöstä ja peruu sovelluksen tilauksen tililtä, joka on tilattava uudelleen.
Se välittää tapahtumat HTTPS-päätepisteeseesi X-EC-Signature-otsikolla allekirjoitettuina tilikohtaisella salaisuudella ja valvoo jokaista yhteyttä ympäri vuorokauden. Ota se käyttöön kutsulla set_social_webhook_destination tai Partner API:n kautta. Hinta on US$ 9 yhteydeltä kuukaudessa ja laskee US$ 0.75:een lisäyhteyksien myötä. Ensimmäiset 3 päivää ovat ilmaisia.
Usein kysytyt kysymykset
Mikä on hub.challenge Instagram-webhookeissa?
Kokonaisluku, jonka Meta lähettää vahvistuspyynnössään GET-pyynnössä. Kun päätepiste on tarkistanut hub.verify_token-arvon, se palauttaa haasteen rungon vastauksena. Tämä todistaa, että päätepiste hallitsee URL-osoitetta.
Miksi hub.mode ja hub.challenge puuttuvat PHP:ssa?
PHP muuttaa parametrinimien pisteet alaviivoiksi, joten Metan vahvistusarvot saapuvat nimillä hub_mode, hub_challenge ja hub_verify_token.
Miten Instagram-webhookit otetaan uudelleen käyttöön, kun Meta on poistanut ne käytöstä?
Korjaa päätepiste ja tilaa tili uudelleen kutsulla POST /<IG_ID>/subscribed_apps samoilla kentillä.
Toimiiko itse allekirjoitettu varmenne Instagram-webhookin päätepisteessä?
Ei. Meta ei tue itse allekirjoitettuja varmenteita. Takaisinkutsu-URL-osoitteen on oltava tavoitettavissa HTTPS:n kautta voimassa olevalla varmenteella, ja tämä on Metan vianmääritysluettelon ensimmäinen kohta.
Lue lisää
Yhdistä ensimmäinen kanavasi kahdessa minuutissa.
Ei alustojen tarkastuksia odotettavana. Yhdistä WhatsApp, Instagram, TikTok tai jokin muu kanava, pyydä sitten tekoälyäsi julkaisemaan, vastaamaan tai raportoimaan ja seuraa, kun se hoitaa homman.
- 3 päivää ilmaiseksi
- Peruuta milloin tahansa
- Vain viralliset API:t
- Valvottu 24/7
Vahvistettu