Instagram webhook-gebeurtenissen: reacties, vermeldingen en DM's
Instagram-webhook-gebeurtenissen melden activiteit op een professioneel account zodra die zich voordoet: nieuwe reacties, @vermeldingen en DM's. Meta stuurt elke gebeurtenis als JSON via POST naar het HTTPS-endpoint van de verbonden app en probeert een mislukte levering daarnaar tot 36 uur opnieuw. easyCoexistence geeft elke gebeurtenis één keer door aan je endpoint, per account ondertekend, zonder nieuwe pogingen. Bij Instagram Login komen vermeldingen binnen via de melding over reacties.
Hoelang Meta een mislukte levering naar het endpoint van de app opnieuw probeert voordat het wordt opgegeven.
De meeste updates bundelt Meta in één webhook-levering, al garandeert Meta dat niet.
De vlag die Meta zet op berichtgebeurtenissen die het account zelf heeft verstuurd.
Alleen media op openbare accounts activeert meldingen voor reacties en vermeldingen.
Welke gebeurtenissen zijn er?
Voor een professioneel account dat met Instagram Login is verbonden, komen drie soorten activiteit binnen als gebeurtenis:
- Reacties: een nieuwe reactie op de media van het account, met de reactie-ID, de Instagram-ID (gebonden aan deze app) en gebruikersnaam van de auteur, de tekst, en de media-ID en het mediatype.
- Vermeldingen: bij Instagram Login komen ze binnen in de meldingen over reacties, niet als eigen veld.
- Berichten: een DM naar het account, met de afzender, de ontvanger, een tijdstempel en het bericht zelf, inclusief tekst, bijlagen en Story-antwoorden.
Hoe komen de gebeurtenissen bij je endpoint?
Meta levert Instagram-webhooks af aan de app waarmee het account is verbonden. easyCoexistence ontvangt ze en geeft elke gebeurtenis door aan het HTTPS-endpoint dat je voor dat account hebt ingesteld, zodra ze binnenkomen, ondertekend met een geheim voor dat account.
Stel het endpoint in met set_social_webhook_destination vanuit Claude of ChatGPT, of met de Partner API via PUT /channels/:id/webhook. Het ondertekeningsgeheim wordt één keer getoond, opnieuw instellen van het endpoint geeft een nieuw geheim uit, en null als URL zet het doorsturen uit.
Hoe ziet een levering eruit?
Een POST met een JSON-body die het platform bevat, de account_id die list_social_accounts aan de verbinding geeft, de external_id van het Instagram-account, en entry: de webhook-entry van Meta voor de gebeurtenis, ongewijzigd. Een DM komt op dezelfde manier binnen, met een messaging-array in plaats van changes. Een nieuwe reactie ziet er zo uit:
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793318400,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}Hoe verifieer je een levering?
Elke levering bevat een X-EC-Signature-header in de vorm t=<unix>,v1=<hex>, waarbij v1 de HMAC-SHA256 is van de tijdstempel, een punt en de ruwe verzoekbody, ondertekend met het ondertekeningsgeheim van het account. Bereken hem over de ruwe body precies zoals ontvangen, vergelijk in constante tijd, en wijs een tijdstempel die ouder is dan 5 minuten af.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}Wordt een levering opnieuw geprobeerd?
Niet door easyCoexistence: het doorsturen geeft elke gebeurtenis één keer door, in het geheugen, en houdt geen kopie over om vanuit opnieuw te proberen. Antwoord snel met een 2xx en voer het werk daarna uit, en sla op wat je nodig hebt zodra het binnenkomt, want Meta houdt ook geen geschiedenis van eerdere meldingen bij die je kunt opvragen.
Meta zelf probeert een mislukte levering aan de app tot 36 uur opnieuw, dus dezelfde gebeurtenis kan af en toe twee keer bij je aankomen: ontdubbel op de reactie-ID of de mid van het bericht.
Waar moet een verwerker verder op letten?
Een paar details in de payloads van Meta die een eerste verwerker laten struikelen:
is_echo: een berichtgebeurtenis metis_echoop true is door het account zelf verstuurd, dus die heeft geen antwoord nodig.- Story-antwoorden: een DM die op een Story antwoordt, bevat
reply_tomet de ID en URL van de Story. - Story-vermeldingen: komen binnen als bericht waarvan het bijlagetype
story_mentionis. - time: wanneer Meta de melding verstuurde, niet wanneer de reactie of het bericht is gemaakt; de eigen tijdstempel van een bericht staat in de messaging-entry ervan.
- Album-ID's: reactiegebeurtenissen bevatten die niet; zoek het album op met de reactie-ID.
Veelgemaakte fouten
- Het werk doen vóór het antwoord. Doorsturen probeert niet opnieuw, dus geef meteen een 2xx terug en verwerk de gebeurtenis daarna.
- De ondertekening verifiëren op geparsede JSON. Bereken de HMAC over de ruwe body precies zoals die binnenkwam.
- Op echo's antwoorden. Een berichtgebeurtenis met is_echo is er één die het account zelf verstuurde, en een antwoord erop start een lus.
- Ontdubbelen overslaan. Meta kan na een fout dezelfde gebeurtenis opnieuw leveren, dus sleutel op de reactie-ID of de mid van het bericht.
easyCoexistence stuurt de reacties, vermeldingen en DM's van het Instagram-account zodra ze binnenkomen door naar je HTTPS-endpoint, ondertekend met een geheim voor dat account en zonder kopie onderweg. Zet het aan met set_social_webhook_destination vanuit Claude of ChatGPT, of met de Partner API. US$ 9 tot US$ 0.75 per verbinding per maand, dalend naarmate je meer verbindingen toevoegt, met de eerste 3 dagen gratis.
Veelgestelde vragen
Wat betekent het time-veld in een Instagram-webhook?
Wanneer Meta de melding verstuurde, niet wanneer de reactie of het bericht is gemaakt. De eigen tijdstempel van een DM staat in de messaging-entry ervan.
Probeert Meta mislukte Instagram-webhook-leveringen opnieuw?
Ja. Meta probeert een mislukte levering aan de app tot 36 uur opnieuw, dus dezelfde gebeurtenis kan af en toe twee keer aankomen: ontdubbel op de reactie-ID of de mid van het bericht. easyCoexistence geeft elke gebeurtenis één keer door aan je endpoint, dus antwoord snel met een 2xx.
Hoeveel updates kan één Instagram-webhook-levering bevatten?
Tot 1.000 wanneer Meta ze bundelt, al garandeert Meta het bundelen niet. Loop over de hele entry-array in plaats van alleen het eerste item te lezen.
Hebben vermeldingen een eigen gebeurtenis?
Niet bij Instagram Login. Meta neemt vermeldingen op in de melding over reacties, dus ze komen via hetzelfde pad binnen als reacties.
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