Se connecterCommencer l’essai gratuit
easyCoexistence API officielles

Événements webhook Instagram : commentaires, mentions et DM

Les événements webhook Instagram signalent en temps réel l'activité d'un compte professionnel : nouveaux commentaires, @mentions et DM. Meta envoie chacun d'eux en POST, au format JSON, vers l'endpoint HTTPS de l'application connectée, et réessaie une livraison échouée vers celui-ci pendant jusqu'à 36 heures. easyCoexistence transmet chaque événement à votre endpoint une seule fois, signé pour chaque compte, sans nouvelle tentative. Avec Instagram Login, les mentions arrivent dans la notification des commentaires.

36 hours

Durée pendant laquelle Meta continue de réessayer une livraison échouée vers l'endpoint de l'application avant de l'abandonner.

1,000

La plupart des mises à jour sont regroupées par Meta dans une seule livraison webhook, sans que Meta garantisse ce regroupement.

is_echo

Indicateur que Meta applique aux événements de message envoyés par le compte lui-même.

Public

Seuls les médias des comptes publics déclenchent les notifications de commentaires et de mentions.

Quels sont les événements ?

Pour un compte professionnel connecté avec Instagram Login, trois types d'activité arrivent sous forme d'événements :

  • Commentaires : un nouveau commentaire sur les médias du compte, avec l'ID du commentaire, l'identifiant Instagram de l'auteur et son nom d'utilisateur, le texte, ainsi que l'ID et le type du média.
  • Mentions : avec Instagram Login, elles figurent dans la notification des commentaires plutôt que dans un champ propre.
  • Messages : un DM reçu par le compte, avec l'expéditeur, le destinataire, un horodatage et le message lui-même, y compris le texte, les pièces jointes et les réponses aux Stories.

Comment les événements parviennent-ils à votre endpoint ?

Meta livre les webhooks Instagram à l'application à laquelle le compte est connecté. easyCoexistence les reçoit et transmet chacun d'eux à l'endpoint HTTPS que vous avez défini pour ce compte, dès son arrivée, signé avec un secret propre à ce compte.

Définissez l'endpoint avec set_social_webhook_destination depuis Claude ou ChatGPT, ou avec la Partner API via PUT /channels/:id/webhook. Le secret de signature n'est affiché qu'une fois : redéfinir l'endpoint en génère un nouveau, et passer null comme URL désactive le transfert.

À quoi ressemble une livraison ?

Un POST avec un corps JSON contenant la plateforme, le account_id que renvoie list_social_accounts pour la connexion, l'external_id du compte Instagram et entry : l'entrée webhook de Meta pour l'événement, sans modification. Un DM arrive de la même façon, avec un tableau messaging à la place de changes. Un nouveau commentaire se présente ainsi :

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>" }
        }
      }
    ]
  }
}

Comment vérifier une livraison ?

Chaque livraison porte un en-tête X-EC-Signature au format t=<unix>,v1=<hex>, où v1 est le HMAC-SHA256 de l'horodatage, d'un point et du corps brut de la requête, avec pour clé le secret de signature du compte. Calculez-le sur le corps brut tel que reçu, comparez-le en temps constant et rejetez tout horodatage antérieur de plus de 5 minutes.

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));
}

Une livraison est-elle réessayée ?

Pas par easyCoexistence : le transfert envoie chaque événement une seule fois, en mémoire, et ne conserve aucune copie pour réessayer. Répondez rapidement par un 2xx et effectuez le traitement ensuite. Enregistrez ce dont vous avez besoin dès réception, car Meta ne conserve pas non plus d'historique interrogeable des notifications passées.

En revanche, Meta réessaie lui-même une livraison échouée vers l'application pendant jusqu'à 36 heures : un même événement peut donc vous parvenir deux fois à l'occasion. Dédoublonnez sur l'ID du commentaire ou sur le mid du message.

Que doit vérifier un gestionnaire d'événements ?

Quelques détails des payloads de Meta piègent souvent un premier gestionnaire :

  • is_echo : un événement de message dont is_echo vaut true a été envoyé par le compte lui-même, il n'appelle donc aucune réponse.
  • Réponses aux Stories : un DM qui répond à une Story contient reply_to, avec l'ID et l'URL de la Story.
  • Mentions dans les Stories : elles arrivent sous forme de message dont le type de pièce jointe est story_mention.
  • time : l'heure à laquelle Meta a envoyé la notification, et non celle du commentaire ou du message. L'horodatage propre à un message figure dans son entrée messaging.
  • IDs d'album : les événements de commentaire ne les incluent pas ; recherchez l'album à partir de l'ID du commentaire.

Erreurs courantes

  • Traiter avant de répondre. Le transfert ne réessaie pas, donc renvoyez un 2xx immédiatement et traitez l'événement ensuite.
  • Vérifier la signature sur du JSON déjà analysé. Calculez le HMAC sur le corps brut, exactement tel qu'il est arrivé.
  • Répondre aux échos. Un événement de message dont is_echo est défini est un message envoyé par le compte, et y répondre lance une boucle.
  • Omettre le dédoublonnage. Meta peut renvoyer le même événement après un échec, donc utilisez l'ID du commentaire ou le mid du message comme clé.
Faire cela avec EasyCoexistence

easyCoexistence transmet à votre endpoint HTTPS les commentaires, mentions et DM du compte Instagram dès leur arrivée, signés avec un secret propre à ce compte et sans conserver de copie au passage. Activez-le avec set_social_webhook_destination depuis Claude ou ChatGPT, ou avec la Partner API. De US$ 9 à US$ 0,75 par connexion et par mois, dégressif à mesure que vous ajoutez des connexions, avec un essai gratuit de 3 jours.

Questions fréquemment posées

Que signifie le champ time dans un webhook Instagram ?

L'heure à laquelle Meta a envoyé la notification, et non celle du commentaire ou du message. L'horodatage d'un DM figure dans son entrée messaging.

Meta réessaie-t-il les livraisons webhook Instagram échouées ?

Oui. Meta réessaie une livraison échouée vers l'application pendant jusqu'à 36 heures, donc un même événement peut arriver deux fois à l'occasion : dédoublonnez sur l'ID du commentaire ou sur le mid du message. easyCoexistence transmet chaque événement à votre endpoint une seule fois, répondez donc rapidement par un 2xx.

Combien de mises à jour une livraison webhook Instagram peut-elle contenir ?

Jusqu'à 1 000 lorsque Meta les regroupe, sans que Meta garantisse ce regroupement. Parcourez tout le tableau entry plutôt que de ne lire que son premier élément.

Les mentions ont-elles leur propre événement ?

Pas avec Instagram Login. Meta les inclut dans la notification des commentaires, elles arrivent donc par le même chemin que les commentaires.

Poursuivre la lecture

Connectez votre premier canal en deux minutes.

Aucune validation de plateforme à attendre. Connectez WhatsApp, Instagram, TikTok ou un autre canal, puis demandez à votre IA de publier, de répondre ou de faire un rapport, et regardez-la travailler.

  • 3 jours gratuits
  • Résiliable à tout moment
  • API officielles uniquement
  • Supervisé 24/7

Vérifié le