Se connecterCommencer l’essai gratuit
easyCoexistence API officielles

Vérification des webhooks Instagram : hub.challenge et X-Hub-Signature-256

La mise en place de webhooks Instagram exige un endpoint HTTPS qui répond à la requête GET de vérification de Meta, contenant hub.mode défini sur subscribe, hub.verify_token et hub.challenge, en contrôlant le token puis en renvoyant le challenge. Meta envoie ensuite en POST des événements JSON signés dans X-Hub-Signature-256 avec le secret de l'application, une fois que celle-ci s'est abonnée aux champs et que chaque compte est abonné via son edge subscribed_apps.

easyCoexistence gère le côté Meta : son application passe la vérification, contrôle X-Hub-Signature-256, abonne chaque compte Instagram connecté aux commentaires, aux messages et aux mentions, et transfère les événements vers votre endpoint HTTPS signés avec X-EC-Signature et un secret propre à chaque compte, tout en surveillant chaque connexion en permanence.

subscribe

La valeur hub.mode est toujours présente dans la requête de vérification de Meta.

36 hours

Durée pendant laquelle Meta relance une notification en échec, à fréquence décroissante, avant de l'abandonner.

15 minutes

De livraisons de messages en échec avant que Meta n'envoie une alerte au compte développeur.

1 hour

De livraisons de messages en échec avant une alerte Webhooks Disabled et la désinscription de l'application du compte.

Live

Mode d'application que Meta exige avant qu'une application reçoive les notifications des comptes de ses utilisateurs.

Comment fonctionne la configuration des webhooks Instagram ?

En quatre étapes, dans l'ordre du guide de Meta. L'endpoint doit passer la vérification avant que le moindre champ puisse être sélectionné, l'application doit être en mode Live pour recevoir les notifications des comptes de ses utilisateurs, et la vérification d'entreprise est requise pour l'accès en production.

1EndpointAn HTTPS URL with a valid certificate answers the verification GET
2App fieldsCallback URL, verify token and fields set in the App Dashboard
3Each accountPOST /<IG_ID>/subscribed_apps turns its notifications on
4TestA dashboard test, then a real event, reach the endpoint

Que contient la requête de vérification ?

Un GET vers l'URL de callback, envoyé dès que le produit Webhooks est configuré dans l'App Dashboard. Lorsque hub.verify_token correspond au token de l'endpoint, la réponse est un 200 dont le corps entier est la valeur de hub.challenge ; sinon, un 403. Le dashboard indique si l'endpoint a réussi la vérification.

  • hub.mode : toujours subscribe.
  • hub.challenge : un entier généré par Meta, que l'endpoint doit renvoyer.
  • hub.verify_token : la chaîne saisie dans le champ Verify Token du dashboard, que seuls Meta et l'endpoint doivent connaître.
  • En PHP, les points de ces noms deviennent des tirets bas, si bien que les valeurs arrivent sous les noms hub_mode, hub_challenge et hub_verify_token.
The verification request and its answer
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

1158201444

Où sont définis le callback et les champs ?

Dans l'App Dashboard, sous Instagram, API setup with Instagram login, Configure webhooks : l'URL de callback et le verify token s'y renseignent, et leur enregistrement déclenche la requête de vérification. Le produit Instagram démarre abonné à comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral et messaging_seen, et Manage permet de se désabonner de l'un d'entre eux. Le bouton Test envoie une notification d'exemple pour un champ sélectionné.

Comment vérifier X-Hub-Signature-256 ?

Meta signe chaque notification d'événement avec un HMAC-SHA256 du payload, calculé avec le secret de l'application, et l'envoie dans X-Hub-Signature-256 sous la forme sha256= suivi du digest hexadécimal. Le récepteur recalcule le même HMAC sur le corps brut de la requête et le compare à l'en-tête en temps constant. Le guide de messagerie de Meta précise que la signature couvre le payload avec les caractères Unicode échappés : hacher un JSON décodé ou re-sérialisé donne donc un résultat différent.

Node.js: answering verification and checking X-Hub-Signature-256
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);

Pourquoi seul le secret de l'application peut-il la vérifier ?

Parce que la signature est un HMAC dont la clé est ce secret. Sans lui, personne ne peut calculer la valeur attendue, et personne possédant une copie d'un payload ne peut en forger un ; la vérification doit donc se faire sur le serveur qui reçoit les requêtes de Meta pour l'application. Meta demande que les secrets d'application, les tokens d'accès et les identifiants client restent hors des logs et des demandes de support. Un système qui reçoit des événements transmis par une autre application ne peut pas du tout vérifier la signature de Meta et doit s'appuyer sur la signature propre à cette application.

Pourquoi chaque compte a-t-il besoin de son propre abonnement ?

Parce que l'App Dashboard définit ce que l'application peut recevoir, et que les notifications d'un compte ne commencent qu'une fois ce compte abonné également. Avec Instagram Login, envoyez POST /<IG_ID>/subscribed_apps à graph.instagram.com avec le token d'accès utilisateur Instagram du compte et subscribed_fields, qui liste les champs sélectionnés pour l'application, séparés par des virgules. Un appel réussi renvoie success défini à true.

Subscribing one account to comments and messages
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
  ?subscribed_fields=comments,messages
  &access_token=<INSTAGRAM_USER_ACCESS_TOKEN>

{ "success": true }

Que fait Meta lorsque les livraisons échouent ?

Il relance, puis abandonne. Le guide de Meta demande une réponse 200 OK à chaque notification et prévient que le regroupement, jusqu'à 1 000 mises à jour, n'est pas garanti. Une mise à jour en échec est relancée immédiatement, puis quelques fois de plus à fréquence décroissante pendant 36 heures, et abandonnée ensuite, de sorte que le même événement peut arriver deux fois. Les événements de messagerie suivent les règles de livraison des messages de Meta, plus rapides :

  • Un 200 OK est attendu sous 5 secondes, et une livraison en échec reçoit quelques relances immédiates : dédupliquez donc sur le mid du message.
  • Après 15 minutes d'échecs, une alerte est envoyée au compte développeur.
  • Après une heure d'échecs, une alerte Webhooks Disabled suit, et l'application est désabonnée des webhooks du compte jusqu'à ce qu'elle se réabonne.
  • Les messages envoyés pendant une panne peuvent arriver dans le désordre : triez-les par horodatage.

Que vérifier lorsque rien n'arrive ?

La checklist de dépannage de Meta, qui couvre la plupart des endpoints muets, dans cet ordre :

  • L'URL de callback a réussi sa vérification et est joignable en HTTPS avec un certificat valide ; les certificats auto-signés ne sont pas pris en charge.
  • L'application a sélectionné le champ et dispose du niveau d'accès requis, Advanced Access pour comments et live_comments.
  • Les notifications sont activées pour le compte via subscribed_apps, avec un token issu de la même configuration de connexion.
  • Le compte respecte les règles du champ : les notifications de commentaires nécessitent un média appartenant à un compte public.
  • Le serveur renvoie success avant de lancer les traitements lents.

Pourquoi easyCoexistence signe-t-il à nouveau les événements transférés ?

Parce que la signature de Meta ne peut pas être transmise. L'application d'easyCoexistence reçoit la livraison de Meta, vérifie X-Hub-Signature-256 avec son propre secret d'application, répond immédiatement à Meta, et envoie en POST chaque entrée d'un compte connecté vers l'endpoint configuré pour ce compte, dans un nouveau corps composé de platform, account_id, external_id et entry. L'en-tête de Meta n'est pas transmis et ne pourrait pas être vérifié sans ce secret ; chaque transfert porte donc Content-Type: application/json et X-EC-Signature, calculé avec un secret propre à ce seul compte.

Comment vérifier X-EC-Signature ?

L'en-tête se présente sous la forme t=<unix>,v1=<hex>, où v1 est le HMAC-SHA256 hexadécimal de l'horodatage, d'un point et du corps brut, calculé avec le secret de signature du compte. Recalculez-le sur les octets exactement tels que reçus, comparez en temps constant, et rejetez tout horodatage vieux de plus de 5 minutes.

  • Le secret commence par whsec_ et n'est affiché qu'une fois, par set_social_webhook_destination ou PUT /channels/:id/webhook lors de la définition de l'URL.
  • Redéfinir l'URL émet un nouveau secret, et une URL nulle désactive le transfert.
  • Chaque événement est envoyé une seule fois, avec un délai d'attente de 8 secondes, sans suivre les redirections, vers une adresse HTTPS qui se résout en IP publique.
  • Supprimer la connexion désabonne le compte des webhooks de Meta et efface son endpoint et son secret.
Python: checking X-EC-Signature
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())

Erreurs courantes

  • Renvoyer le challenge en JSON ou entre guillemets. Meta attend la valeur de hub.challenge elle-même comme corps, avec un statut 200.
  • Hacher un corps parsé. Un parseur JSON écarte les octets exacts signés par Meta : conservez donc le corps brut pour le HMAC et parsez-le ensuite.
  • Abonner l'application et oublier le compte. Tant que POST /<IG_ID>/subscribed_apps n'a pas réussi pour un compte, aucune notification ne lui parvient.
  • Laisser un endpoint en échec pendant une heure. Meta désactive les webhooks de messagerie et désabonne l'application du compte, qu'il faut alors réabonner.
Faire cela avec EasyCoexistence

Activez-le avec set_social_webhook_destination ou 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

Qu'est-ce que hub.challenge dans les webhooks Instagram ?

Un entier envoyé par Meta dans sa requête GET de vérification. Après avoir contrôlé hub.verify_token, l'endpoint le renvoie comme corps de réponse, ce qui prouve qu'il contrôle l'URL.

Pourquoi hub.mode et hub.challenge n'apparaissent-ils pas en PHP ?

PHP transforme les points des noms de paramètres en tirets bas : les valeurs de vérification de Meta arrivent donc sous les noms hub_mode, hub_challenge et hub_verify_token.

Comment réactiver les webhooks Instagram après leur désactivation par Meta ?

Corrigez l'endpoint, puis réabonnez le compte avec POST /<IG_ID>/subscribed_apps et les mêmes champs.

Un certificat auto-signé fonctionne-t-il pour un endpoint de webhook Instagram ?

Non, Meta ne prend pas en charge les certificats auto-signés : l'URL de callback doit être joignable en HTTPS avec un certificat valide, premier point de la checklist de dépannage de Meta.

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