Instagram webhook-verificatie: hub.challenge en X-Hub-Signature-256
Instagram-webhooks instellen vraagt om een HTTPS-endpoint dat de verificatie-GET van Meta beantwoordt. Die GET bevat hub.mode met de waarde subscribe, hub.verify_token en hub.challenge. Het endpoint controleert het token en geeft de challenge terug. Daarna stuurt Meta JSON-events die in X-Hub-Signature-256 zijn ondertekend met het geheim van de app, zodra de app velden kiest en elk account via de subscribed_apps-edge abonneert.
easyCoexistence regelt de Meta-kant: de app doorstaat de verificatie, controleert X-Hub-Signature-256, abonneert elk verbonden Instagram-account op comments, messages en mentions en stuurt de events door naar je HTTPS-endpoint.
Meta stuurt in het verificatieverzoek altijd de waarde hub.mode mee.
Periode waarin Meta een mislukte melding opnieuw probeert, met afnemende frequentie, voordat die wordt weggegooid.
Aantal mislukte berichtbezorgingen voordat Meta een waarschuwing naar het developeraccount stuurt.
Aantal mislukte berichtbezorgingen voordat een waarschuwing Webhooks Disabled verschijnt en de app het account uitschrijft.
App-modus die Meta vereist voordat een app meldingen ontvangt voor accounts van zijn gebruikers.
Hoe werkt het instellen van Instagram-webhooks?
In vier stappen, in de volgorde van de gids van Meta. Het endpoint moet de verificatie doorstaan voordat een veld kan worden gekozen. De app moet Live zijn om meldingen te ontvangen voor accounts van zijn gebruikers, en bedrijfsverificatie is vereist voor productietoegang.
Wat bevat het verificatieverzoek?
Een GET naar de callback-URL, die wordt verzonden zodra het product Webhooks is ingesteld in het App Dashboard. Komt hub.verify_token overeen met het eigen token van het endpoint, dan is het antwoord een 200 met de waarde van hub.challenge als volledige body. Anders volgt een 403. Het dashboard meldt of het endpoint is geslaagd.
- hub.mode: altijd subscribe.
- hub.challenge: een geheel getal dat Meta genereert en dat het endpoint terug moet sturen.
- hub.
verify_token: de tekst die is ingevoerd in het veld Verify Token van het dashboard, die alleen Meta en het endpoint mogen kennen. - In PHP veranderen de punten in deze namen in underscores, dus de waarden komen binnen als
hub_mode,hub_challengeenhub_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
1158201444Waar worden de callback en de velden ingesteld?
In het App Dashboard, onder Instagram, API setup with Instagram login, Configure webhooks: de callback-URL en het Verify Token gaan daar, en opslaan start het verificatieverzoek. Het Instagram-product start geabonneerd op comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral en messaging_seen, en via Manage kun je elk ervan uitschakelen. De Test-knop stuurt een voorbeeldmelding voor een gekozen veld.
Hoe wordt X-Hub-Signature-256 gecontroleerd?
Meta ondertekent elke melding met een HMAC-SHA256 van de payload, gesleuteld met het geheim van de app, en stuurt die in X-Hub-Signature-256 als sha256= gevolgd door de hex-digest. De ontvanger berekent dezelfde HMAC over de onbewerkte verzoekbody en vergelijkt die in constante tijd met de header. De berichtengids van Meta vermeldt dat de handtekening de payload dekt met Unicode geëscaped, dus gedecodeerde of opnieuw geserialiseerde JSON geeft een ander resultaat.
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);Waarom kan alleen het geheim van de app dit controleren?
Omdat de handtekening een HMAC is die met dat geheim is gesleuteld. Zonder dat geheim kan niemand de verwachte waarde berekenen, en niemand met een kopie van een payload kan er een vervalsen. De controle hoort daarom op de server die Meta's verzoeken voor de app ontvangt. Meta vraagt dat app-geheimen, access-tokens en client-credentials uit logs en supportverzoeken blijven. Een systeem dat events ontvangt die door een andere app zijn doorgegeven, kan Meta's handtekening helemaal niet controleren en vertrouwt in plaats daarvan op de eigen handtekening van die app.
Waarom heeft elk account een eigen abonnement nodig?
Omdat het App Dashboard bepaalt wat de app kan ontvangen, en meldingen voor een account pas beginnen wanneer dat account ook is geabonneerd. Met Instagram Login stuur je POST /<IG_ID>/subscribed_apps naar graph.instagram.com met het Instagram User access-token van het account en subscribed_fields met de velden die voor de app zijn gekozen, gescheiden door komma's. Een geslaagde aanroep geeft success terug als true.
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }Wat doet Meta als leveringen mislukken?
Het probeert het opnieuw en geeft dan op. De gids van Meta vraagt om een 200 OK op elke melding en waarschuwt dat batchen, tot 1.000 updates, niet gegarandeerd is. Een mislukte update wordt meteen opnieuw geprobeerd en daarna nog een paar keer met afnemende frequentie over 36 uur, en daarna weggegooid. Dezelfde gebeurtenis kan dus twee keer binnenkomen. Berichtgebeurtenissen volgen de leveringsregels voor berichten van Meta, die sneller ingrijpen:
- Een 200 OK wordt binnen 5 seconden verwacht, en een mislukte levering krijgt enkele directe nieuwe pogingen, dus dedupliceer op de mid van het bericht.
- Na 15 minuten storing gaat er een waarschuwing naar het developeraccount.
- Na een uur storing volgt een waarschuwing Webhooks Disabled, en de app wordt uitgeschreven van de webhooks van het account tot de app zich opnieuw abonneert.
- Berichten die tijdens een storing zijn verzonden, kunnen door elkaar binnenkomen, dus sorteer ze op timestamp.
Wat moet je controleren als er niets binnenkomt?
De checklist voor probleemoplossing van Meta, die de meeste stille endpoints dekt, in deze volgorde:
- De callback-URL is geslaagd voor de controle en is via HTTPS bereikbaar met een geldig certificaat; zelfondertekende certificaten worden niet ondersteund.
- De app heeft het veld gekozen en heeft het toegangsniveau dat nodig is, Advanced Access voor comments en
live_comments. - Meldingen staan aan voor het account via
subscribed_apps, met een token uit dezelfde logininstelling. - Het account voldoet aan de regels van het veld: meldingen voor comments vereisen media van een openbaar account.
- De server geeft success terug voordat hij aan langzaam werk begint.
Waarom ondertekent easyCoexistence doorgestuurde events opnieuw?
Omdat de handtekening van Meta niet mee kan reizen. De app van easyCoexistence ontvangt de levering van Meta, controleert X-Hub-Signature-256 met het eigen app-geheim, antwoordt Meta meteen en stuurt elke entry voor een verbonden account door naar het endpoint dat voor dat account is ingesteld. Dat gebeurt in een nieuwe body met platform, account_id, external_id en entry. De header van Meta wordt niet doorgestuurd en kon zonder dat geheim niet worden gecontroleerd. Daarom draagt elke doorgestuurde oproep Content-Type: application/json en X-EC-Signature, gesleuteld met een geheim dat bij dat ene account hoort.
Hoe verifieer je X-EC-Signature?
De header luidt t=<unix>,v1=<hex>, waarbij v1 de hex-HMAC-SHA256 is van de tijdstempel, een punt en de onbewerkte body, gesleuteld met het ondertekeningsgeheim van het account. Bereken die opnieuw over de bytes precies zoals ontvangen, vergelijk in constante tijd, en wijs een tijdstempel af die ouder is dan 5 minuten.
- Het geheim begint met whsec_ en wordt één keer getoond, door
set_social_webhook_destinationof PUT /channels/:id/webhook wanneer de URL wordt ingesteld. - Het URL opnieuw instellen geeft een nieuw geheim, en een URL van null zet het doorsturen uit.
- Elk event wordt één keer verstuurd, met maximaal 8 seconden wachttijd, zonder redirects te volgen, naar een HTTPS-adres dat naar een publiek IP-adres verwijst.
- Het verwijderen van de verbinding haalt het account uit Meta's webhooks en wist het endpoint en het geheim.
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())Veelgemaakte fouten
- Het challenge als JSON of tussen aanhalingstekens teruggeven. Meta verwacht de waarde van hub.challenge zelf als body, met status 200.
- Een geparseerde body hashen. Een JSON-parser gooit de exacte bytes weg die Meta heeft ondertekend, dus bewaar de onbewerkte body voor de HMAC en parseer hem daarna.
- De app abonneren en het account vergeten. Totdat POST /<IG_ID>/subscribed_apps slaagt voor een account, komen er geen meldingen voor dat account binnen.
- Een endpoint een uur laten falen. Meta schakelt berichtwebhooks uit en schrijft de app uit van het account, dat daarna opnieuw moet worden geabonneerd.
Dat gebeurt ondertekend met X-EC-Signature en een geheim per account, terwijl elke verbinding dag en nacht wordt bewaakt. Zet het aan met set_social_webhook_destination of de Partner API. Van US$ 9 tot US$ 0,75 per verbinding per maand, dalend naarmate je meer verbindingen toevoegt, met 3 dagen gratis proefperiode.
Veelgestelde vragen
Wat is hub.challenge in Instagram-webhooks?
Een geheel getal dat Meta meestuurt in zijn verificatie-GET. Na het controleren van hub.verify_token stuurt het endpoint het terug als antwoordbody, wat bewijst dat het de URL beheert.
Waarom ontbreken hub.mode en hub.challenge in PHP?
PHP zet de punten in parameternamen om in underscores, dus de verificatiewaarden van Meta komen binnen als hub_mode, hub_challenge en hub_verify_token.
Hoe zet ik Instagram-webhooks weer aan nadat Meta ze heeft uitgeschakeld?
Los het endpoint op en abonneer het account daarna opnieuw met POST /<IG_ID>/subscribed_apps en dezelfde velden.
Werkt een zelfondertekend certificaat voor een Instagram-webhookendpoint?
Nee, Meta ondersteunt geen zelfondertekende certificaten: de callback-URL moet via HTTPS bereikbaar zijn met een geldig certificaat, het eerste punt op de checklist van Meta voor probleemoplossing.
Lees verder
Koppel je eerste kanaal in twee minuten.
Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.
- 3 dagen gratis
- Op elk moment opzegbaar
- Alleen officiële API's
- 24/7 bewaakt
Geverifieerd op