Evenimente webhook Instagram: comentarii, mențiuni și mesaje directe
Evenimentele webhook Instagram raportează activitatea de pe un cont profesional pe măsură ce are loc: comentarii noi, @mențiuni și mesaje directe. Meta trimite fiecare eveniment ca JSON prin POST către endpoint-ul HTTPS al aplicației conectate și reîncearcă o livrare eșuată către acesta timp de până la 36 de ore. easyCoexistence transmite fiecare eveniment către endpoint-ul dumneavoastră o singură dată, semnat pentru fiecare cont, fără reîncercări. Cu Instagram Login, mențiunile sosesc în cadrul notificării despre comentarii.
Cât timp reîncearcă Meta o livrare eșuată către endpoint-ul aplicației înainte de a o renunța.
Majoritatea actualizărilor sunt grupate de Meta într-o singură livrare webhook, deși Meta nu garantează gruparea.
Indicatorul pe care Meta îl setează la evenimentele de mesaje trimise chiar de contul respectiv.
Doar conținutul media de pe conturile publice declanșează notificările pentru comentarii și mențiuni.
Ce evenimente există?
Pentru un cont profesional conectat prin Instagram Login, trei tipuri de activitate sosesc ca evenimente:
- Comentarii: un comentariu nou la conținutul media al contului, cu ID-ul comentariului, ID-ul autorului (specific Instagram) și numele de utilizator, textul, precum și ID-ul și tipul conținutului media.
- Mențiuni: cu Instagram Login sosesc în cadrul notificării despre comentarii, nu ca un câmp propriu.
- Mesaje directe: un DM către cont, cu expeditorul, destinatarul, data și ora și mesajul propriu-zis, inclusiv text, atașamente și răspunsurile la Story.
Cum ajung evenimentele la endpoint-ul dumneavoastră?
Meta livrează webhook-urile Instagram aplicației la care s-a conectat contul. easyCoexistence le primește și transmite fiecare eveniment mai departe către endpoint-ul HTTPS setat pentru contul respectiv, pe măsură ce sosește, semnat cu un secret specific acelui cont.
Setați endpoint-ul cu set_social_webhook_destination din Claude sau ChatGPT, ori cu Partner API prin PUT /channels/:id/webhook. Secretul de semnare se afișează o singură dată, iar setarea din nou a endpoint-ului emite unul nou, iar transmiterea null ca URL oprește transmiterea.
Cum arată o livrare?
Un POST cu un corp JSON care conține platforma, account_id-ul pe care îl dă list_social_accounts pentru conexiune, external_id-ul contului Instagram și entry: intrarea webhook Meta pentru eveniment, nemodificată. Un mesaj direct sosește la fel, cu un array messaging în locul lui changes. Un comentariu nou arată astfel:
{
"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>" }
}
}
]
}
}Cum verificați o livrare?
Fiecare livrare poartă un antet X-EC-Signature în forma t=<unix>,v1=<hex>, unde v1 este HMAC-SHA256 calculat peste marcajul de timp, un punct și corpul brut al cererii, cu cheia secretului de semnare al contului. Calculați-l peste corpul brut exact cum a fost primit, comparați în timp constant și respingeți un marcaj de timp mai vechi de 5 minute.
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));
}Se reîncearcă o livrare?
Nu de către easyCoexistence: transmiterea trimite fiecare eveniment o singură dată, în memorie, și nu păstrează nicio copie din care să reîncerce. Răspundeți rapid cu un 2xx și faceți lucrul după aceea, salvând ce vă trebuie în momentul sosirii, deoarece nici Meta nu păstrează un istoric al notificărilor trecute care să poată fi interogat.
Meta însăși reîncearcă o livrare eșuată către aplicație timp de până la 36 de ore, așa că același eveniment poate ajunge uneori de două ori: deduplicați după ID-ul comentariului sau după mid-ul mesajului.
Ce mai trebuie verificat de un handler?
Câteva detalii din payload-urile Meta care îi încurcă pe cei care scriu primul handler:
is_echo: un eveniment de mesaj cuis_echosetat la true a fost trimis chiar de cont, deci nu are nevoie de răspuns.- Răspunsuri la Story: un DM care răspunde unui Story poartă
reply_tocu ID-ul și URL-ul Story-ului. - Mențiuni în Story: sosesc ca mesaj al cărui tip de atașament este
story_mention. - time: momentul în care Meta a trimis notificarea, nu cel în care a fost făcut comentariul sau mesajul; marcajul de timp al mesajului se află în intrarea sa messaging.
- ID-uri de album: evenimentele de comentariu nu le includ; căutați albumul după ID-ul comentariului.
Greșeli frecvente
- Efectuarea lucrului înainte de răspuns. Transmiterea nu reîncearcă, deci returnați imediat un 2xx și procesați evenimentul după aceea.
- Verificarea semnăturii pe JSON deja analizat. Calculați HMAC-ul peste corpul brut exact cum a sosit.
- Răspunsul la ecouri. Un eveniment de mesaj cu is_echo setat este unul trimis de cont, iar un răspuns la el pornește o buclă.
- Omiterea deduplicării. Meta poate livra din nou același eveniment după o eroare, așa că folosiți drept cheie ID-ul comentariului sau mid-ul mesajului.
easyCoexistence transmite comentariile, mențiunile și mesajele directe ale contului Instagram către endpoint-ul dumneavoastră HTTPS pe măsură ce sosesc, semnate cu un secret specific contului și fără nicio copie păstrată pe drum. Porniți-l cu set_social_webhook_destination din Claude sau ChatGPT, ori cu Partner API. De la US$ 9 până la US$ 0,75 pe conexiune pe lună, scăzând pe măsură ce adăugați conexiuni, cu perioada de probă gratuită de 3 zile.
Întrebări frecvente
Ce înseamnă câmpul time dintr-un webhook Instagram?
Momentul în care Meta a trimis notificarea, nu cel în care a fost făcut comentariul sau mesajul. Marcajul de timp al unui DM se află în intrarea sa messaging.
Retrimite Meta livrările eșuate ale webhook-urilor Instagram?
Da. Meta reîncearcă o livrare eșuată către aplicație timp de până la 36 de ore, așa că același eveniment poate ajunge uneori de două ori: deduplicați după ID-ul comentariului sau după mid-ul mesajului. easyCoexistence transmite fiecare eveniment către endpoint-ul dumneavoastră o singură dată, deci răspundeți rapid cu un 2xx.
Câte actualizări poate conține o livrare webhook Instagram?
Până la 1.000, atunci când Meta le grupează, deși Meta nu garantează gruparea. Parcurgeți întregul array entry, nu doar primul element.
Mențiunile au un eveniment propriu?
Nu cu Instagram Login. Meta include mențiunile în notificarea despre comentarii, deci sosesc pe aceeași cale cu comentariile.
Continuați să citiți
Conectați primul canal în două minute.
Fără recenzii de platformă de așteptat. Conectați WhatsApp, Instagram, TikTok sau alt canal, apoi cereți AI-ului să publice, să răspundă sau să raporteze și urmăriți-l cum lucrează.
- 3 zile gratuit
- Anulați oricând
- Doar API-uri oficiale
- Monitorizat 24/7
Verificat la