Se connecterCommencer l’essai gratuit
easyCoexistence API officielles

Vérification du webhook Facebook : hub.challenge et X-Hub-Signature-256

Facebook vérifie un endpoint de webhook avec une requête GET contenant hub.mode défini sur subscribe, hub.verify_token et hub.challenge ; l'endpoint compare le token à celui de l'App Dashboard et renvoie le challenge dans le corps de la réponse. Chaque événement arrive ensuite sous forme de requête POST signée dans X-Hub-Signature-256 : sha256= suivi du HMAC-SHA256 du payload, calculé avec l'App Secret.

easyCoexistence gère le côté Meta pour chaque Page que vous connectez : son app répond à hub.challenge, vérifie X-Hub-Signature-256 et abonne la Page aux feed, messages et mention, puis transmet les événements à votre endpoint HTTPS, signés avec X-EC-Signature et un secret propre à cette Page.

subscribe

La valeur que hub.mode porte toujours dans la requête de vérification de Meta ; hub.challenge est un entier à renvoyer.

sha256=

Préfixe de X-Hub-Signature-256, suivi de la signature SHA256 que Meta génère à partir du payload et de l'App Secret.

5 seconds

Délai dans lequel un endpoint de webhook Messenger doit répondre 200 OK à chaque notification.

1 hour

Nombre de livraisons en échec avant une alerte Webhooks Disabled et la désinscription de l'app de la Page.

36 hours

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

Que contient la requête de vérification de Meta ?

Une requête GET vers l'URL de callback, envoyée dès que le produit Webhooks est configuré dans l'App Dashboard ou qu'un abonnement est créé via /{app-id}/subscriptions. Elle contient trois paramètres de requête :

  • hub.mode : toujours subscribe.
  • hub.challenge : un entier que l'endpoint doit renvoyer.
  • hub.verify_token : la chaîne saisie dans le champ Verify Token du dashboard.
  • PHP remplace les points par des tirets bas ; il lit donc hub_mode, hub_challenge et hub_verify_token.

Comment l'endpoint doit-il répondre ?

Par un 200 dont le corps entier est la valeur de hub.challenge, mais uniquement lorsque hub.mode vaut subscribe et que hub.verify_token correspond ; tout autre cas reçoit un 403, comme dans l'application d'exemple de Meta. Le dashboard indique si l'endpoint a réussi, et /{app-id}/subscriptions répond par un succès ou une erreur. L'endpoint doit être en HTTPS avec un certificat TLS ou SSL valide, car les certificats auto-signés ne sont pas pris en charge.

Comment X-Hub-Signature-256 est-il calculé ?

Comme un HMAC-SHA256 du payload de la requête, calculé avec l'App Secret de l'app, écrit en hexadécimal minuscule après sha256=. Le guide Messenger de Meta précise que la signature porte sur le payload avec les caractères Unicode échappés : une chaîne telle que äöå compte donc comme \u00e4\u00f6\u00e5. Hachez le corps brut exactement tel que reçu, jamais une copie décodée puis sérialisée à nouveau. Meta indique que la validation est facultative, mais la recommande fortement.

Comment le vérifier dans le code ?

Conservez les octets bruts, calculez le HMAC, comparez en temps constant, puis analysez le corps. get_data de Flask renvoie le corps sans modification, c'est-à-dire ce sur quoi la signature a été calculée ; l'analyser d'abord puis le resérialiser changerait les octets. Voici un petit endpoint qui répond à la vérification et contrôle chaque POST :

Python: hub.challenge and X-Hub-Signature-256
import hashlib, hmac, os
from flask import Flask, abort, request

app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()

@app.get("/webhooks/facebook")
def verify():
    token = request.args.get("hub.verify_token", "")
    if request.args.get("hub.mode") == "subscribe" and hmac.compare_digest(token.encode(), VERIFY_TOKEN.encode()):
        return request.args.get("hub.challenge", ""), 200
    abort(403)

@app.post("/webhooks/facebook")
def receive():
    raw = request.get_data()  # the bytes Meta signed
    expected = "sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected.encode(), request.headers.get("X-Hub-Signature-256", "").encode()):
        abort(401)
    # answer at once; hand request.get_json() to a queue for the work
    return "EVENT_RECEIVED", 200

Qu'attend Meta après la vérification ?

Un 200 OK pour chaque notification, dans les 5 secondes pour les événements Messenger. Meta regroupe jusqu'à 1 000 mises à jour par livraison sans le garantir, et gère les échecs ainsi :

  • Notifications de Page : nouvel essai immédiat, puis quelques tentatives supplémentaires à fréquence décroissante sur 36 heures, puis abandon.
  • Notifications Messenger : quelques essais immédiats ; 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'app est désabonnée de la Page jusqu'à un nouvel abonnement.
  • Les nouvelles tentatives peuvent livrer un événement deux fois et dans le désordre ; dédoublonnez donc, et triez les messages selon leur horodatage.
  • Les notifications passées ne peuvent pas être interrogées ensuite ; stockez donc ce dont vous avez besoin dès leur arrivée.

Comment easyCoexistence passe-t-il les contrôles de Meta ?

Son app Meta dispose d'une seule URL de callback pour les Pages qu'il connecte, et cet endpoint effectue lui-même les deux contrôles. Il répond au GET uniquement lorsque hub.mode vaut subscribe et que le token de vérification correspond, comparé en temps constant, et renvoie 403 dans le cas contraire ; il lit chaque POST comme texte brut, recalcule X-Hub-Signature-256 avec son App Secret, refuse par un 401 une signature non concordante, et répond immédiatement à Meta, en traitant l'événement après la réponse.

Comment easyCoexistence signe-t-il ce qu'il transmet ?

Avec une signature propre, puisque l'en-tête de Meta ne peut être vérifié qu'avec l'App Secret d'easyCoexistence et n'est pas transmis. Chaque entrée d'une Page connectée dont un endpoint est défini est envoyée en POST à celui-ci au format JSON, {platform, account_id, external_id, entry}, avec un en-tête X-EC-Signature de la forme t=<unix>,v1=<hex>, où v1 est le HMAC-SHA256 de l'horodatage, d'un point et du corps brut, calculé avec le secret de signature de cette Page :

  • Le secret commence par whsec_ et n'est affiché qu'une fois, par set_social_webhook_destination ou PUT /channels/:id/webhook sur la Partner API.
  • Définir à nouveau l'URL génère un nouveau secret, et une URL nulle désactive la transmission.
  • Chaque transmission est envoyée une seule fois, avec un délai d'attente de 8 secondes maximum, sans suivre les redirections, vers une adresse HTTPS dont la résolution donne une IP publique.
  • Aucune copie de l'événement n'est conservée : il n'y a donc rien à relancer.

Comment vérifier X-EC-Signature ?

Séparez l'en-tête en t et v1, rejetez un horodatage âgé de plus de 5 minutes, recalculez le HMAC sur t, un point et le corps brut avec le secret de signature de la Page, puis comparez en temps constant. En Node.js, en conservant le corps sous forme d'octets bruts :

Node.js: checking X-EC-Signature on a forwarded event
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.EC_SIGNING_SECRET; // whsec_..., shown once

app.post("/events/facebook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries(
    String(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("="))
  );
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(Buffer.concat([Buffer.from(`${sig.t}.`), req.body]))
    .digest("hex");
  const ok = fresh && typeof sig.v1 === "string" && sig.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
  if (!ok) return res.sendStatus(401);
  res.sendStatus(200); // answer first: forwards are not retried
  const { platform, account_id, external_id, entry } = JSON.parse(req.body.toString("utf8"));
  // queue entry for the work
});

Erreurs courantes

  • Entourer hub.challenge de JSON ou de guillemets. Le corps du 200 doit être la valeur du challenge elle-même.
  • Calculer le HMAC après un parser JSON. Analyser puis resérialiser change les octets, et Meta signe le payload avec les caractères Unicode échappés : hachez donc le corps brut.
  • Faire le travail avant de répondre. Messenger attend un 200 dans les 5 secondes, et une heure d'échecs désabonne l'app de la Page.
  • Vérifier la signature Meta sur les événements transmis. Meta signe avec l'App Secret d'easyCoexistence ; un événement transmis porte X-EC-Signature, vérifié avec le secret de signature de la Page.
Faire cela avec EasyCoexistence

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

D'où vient le verify token ?

Vous le choisissez. C'est la chaîne saisie dans le champ Verify Token lors de la configuration des webhooks dans l'App Dashboard, ou le verify_token envoyé à /{app-id}/subscriptions.

Puis-je tester la vérification avec curl ?

Oui. Le guide Messenger de Meta envoie un GET avec hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED et hub.mode=subscribe, et un endpoint fonctionnel répond CHALLENGE_ACCEPTED.

Que se passe-t-il si mon endpoint échoue pendant une heure ?

Meta envoie une alerte Webhooks Disabled et désabonne l'app de la Page. Une fois l'endpoint corrigé, réabonnez la Page via subscribed_apps.

Ai-je besoin de ma propre app Meta pour recevoir les webhooks d'une Page ?

Non avec easyCoexistence. Meta livre à son app, qui transmet les événements de chaque Page à l'endpoint que vous définissez, signés avec X-EC-Signature.

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