AccediInizia la prova gratuita
easyCoexistence API ufficiali

Eventi webhook di Instagram: commenti, menzioni e DM

Gli eventi webhook di Instagram segnalano in tempo reale l'attività su un account professionale: nuovi commenti, @menzioni e DM. Meta invia ciascuno come JSON tramite POST all'endpoint HTTPS dell'app collegata e riprova per fino a 36 ore una consegna fallita verso di esso. easyCoexistence inoltra ogni evento al tuo endpoint una sola volta, firmato per account, senza nuovi tentativi. Con Instagram Login, le menzioni arrivano all'interno della notifica dei commenti.

36 hours

Per quanto tempo Meta riprova una consegna fallita all'endpoint dell'app prima di scartarla.

1,000

Molti aggiornamenti Meta li raggruppa in un'unica consegna webhook, ma non garantisce il raggruppamento.

is_echo

Il flag che Meta imposta sugli eventi di messaggio inviati dall'account stesso.

Public

Solo i media su account pubblici attivano le notifiche di commenti e menzioni.

Quali eventi esistono?

Per un account professionale collegato con Instagram Login, tre tipi di attività arrivano come eventi:

  • Commenti: un nuovo commento sui media dell'account, con l'ID del commento, l'ID con ambito Instagram e lo username dell'autore, il testo, e l'ID e il tipo del media.
  • Menzioni: con Instagram Login arrivano all'interno della notifica dei commenti, non come campo proprio.
  • Messaggi: un DM all'account, con mittente, destinatario, timestamp e il messaggio stesso, inclusi testo, allegati e risposte alle Story.

Come arrivano gli eventi al tuo endpoint?

Meta consegna i webhook di Instagram all'app a cui l'account è collegato. easyCoexistence li riceve e inoltra ciascuno all'endpoint HTTPS che hai impostato per quell'account, appena arriva, firmato con un segreto dedicato a quell'account.

Imposta l'endpoint con set_social_webhook_destination da Claude o ChatGPT, oppure con la Partner API tramite PUT /channels/:id/webhook. Il segreto di firma viene mostrato una sola volta, impostare di nuovo l'endpoint ne genera uno nuovo, e passare null come URL disattiva l'inoltro.

Com'è fatta una consegna?

Una POST con un corpo JSON che contiene platform, account_id (la connessione restituita da list_social_accounts), external_id dell'account Instagram e entry: l'entry del webhook di Meta per l'evento, invariato. Un DM arriva allo stesso modo, con un array messaging al posto di changes. Un nuovo commento ha questa forma:

A forwarded comment event
{
  "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>" }
        }
      }
    ]
  }
}

Come verifichi una consegna?

Ogni consegna contiene un header X-EC-Signature nella forma t=<unix>,v1=<hex>, dove v1 è l'HMAC-SHA256 del timestamp, di un punto e del corpo grezzo della richiesta, con chiave il segreto di firma dell'account. Calcolalo sul corpo grezzo esattamente come ricevuto, confronta in tempo costante e rifiuta un timestamp più vecchio di 5 minuti.

Node.js: verifying X-EC-Signature
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));
}

Una consegna viene ritentata?

easyCoexistence non ritenta: l'inoltro passa ogni evento una sola volta, in memoria, e non conserva alcuna copia da cui riprovare. Rispondi subito con un 2xx e svolgi il lavoro dopo, e salva ciò che ti serve appena arriva, perché anche Meta non conserva uno storico delle notifiche passate che si possa interrogare.

Meta stessa riprova una consegna fallita all'app per fino a 36 ore, quindi lo stesso evento può occasionalmente arrivare due volte: deduplica sull'ID del commento o sul mid del messaggio.

Cos'altro deve controllare un handler?

Alcuni dettagli nei payload di Meta che fanno inciampare un primo handler:

  • is_echo: un evento di messaggio con is_echo impostato a true è stato inviato dall'account stesso, quindi non richiede risposta.
  • Risposte alle Story: un DM che risponde a una Story contiene reply_to con l'ID e l'URL della Story.
  • Menzioni nelle Story: arrivano come messaggio il cui tipo di allegato è story_mention.
  • time: l'ora in cui Meta ha inviato la notifica, non quella in cui è stato fatto il commento o il messaggio; il timestamp del messaggio si trova nella sua voce messaging.
  • ID degli album: gli eventi di commento non li includono; cerca l'album con l'ID del commento.

Errori comuni

  • Fare il lavoro prima di rispondere. L'inoltro non ritenta, quindi restituisci subito un 2xx ed elabora l'evento dopo.
  • Verificare la firma sul JSON già analizzato. Calcola l'HMAC sul corpo grezzo esattamente come è arrivato.
  • Rispondere agli echo. Un evento di messaggio con is_echo impostato è stato inviato dall'account, e rispondergli avvia un loop.
  • Saltare la deduplica. Meta può consegnare di nuovo lo stesso evento dopo un errore, quindi usa come chiave l'ID del commento o il mid del messaggio.
Farlo con EasyCoexistence

easyCoexistence inoltra i commenti, le menzioni e i DM dell'account Instagram al tuo endpoint HTTPS appena arrivano, firmati con un segreto per quell'account e senza conservare copie lungo il percorso. Attivalo con set_social_webhook_destination da Claude o ChatGPT, oppure con la Partner API. Da US$ 9 a US$ 0,75 per connessione al mese, con prezzo che scende man mano che aggiungi connessioni, e i primi 3 giorni di prova gratuita.

Domande frequenti

Cosa significa il campo time in un webhook di Instagram?

L'ora in cui Meta ha inviato la notifica, non quella in cui sono stati fatti il commento o il messaggio. Il timestamp di un DM si trova nella sua voce messaging.

Meta riprova le consegne webhook di Instagram fallite?

Sì. Meta riprova una consegna fallita all'app per fino a 36 ore, quindi lo stesso evento può occasionalmente arrivare due volte: deduplica sull'ID del commento o sul mid del messaggio. easyCoexistence inoltra ogni evento al tuo endpoint una sola volta, quindi rispondi subito con un 2xx.

Quanti aggiornamenti può contenere una sola consegna webhook di Instagram?

Fino a 1.000 quando Meta li raggruppa, anche se Meta non garantisce il raggruppamento. Scorri l'intero array entry invece di leggere solo il primo elemento.

Le menzioni hanno un evento proprio?

Non con Instagram Login. Meta le include nella notifica dei commenti, quindi arrivano sullo stesso percorso dei commenti.

Continua a leggere

Collega il tuo primo canale in due minuti.

Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.

  • 3 giorni gratis
  • Disdici quando vuoi
  • Solo API ufficiali
  • Monitorato 24/7

Verificato il