Se connecterCommencer l’essai gratuit
Meta Tech Provider

Comment les messages WhatsApp arrivent sur votre serveur : direct ou géré, et vérification de la signature

Chaque numéro connecté via easyCoexistence a un mode de réception. Directement vers votre système (direct) : Meta envoie ses webhooks à votre endpoint HTTPS, un secret dans l'URL sert d'identifiant, et les automatisations sont désactivées. Via easyCoexistence (géré) : Meta livre à easyCoexistence, les automatisations peuvent répondre, et une URL de transfert facultative reçoit la valeur d'origine de Meta avec les détails de la connexion, signée avec X-EC-Signature pour que vous puissiez la vérifier.

7 attempts

Tentatives par livraison transférée, espacées de 1 min, 5 min, 30 min, 2 h, 6 h et 24 h, soit environ 33 heures au total.

10 s

Délai qu'attend chaque tentative de transfert pour une réponse 2xx avant de la compter comme échouée.

5 min

Limite suggérée sur l'âge du t de la signature ; les relances sont à nouveau signées, donc les livraisons authentiques restent dans cette limite.

7 days

Durée pendant laquelle Meta relance un webhook direct qui a reçu autre chose qu'un HTTP 200, ce qui peut répéter des messages.

3 MB

Plus gros payload de webhook envoyé par Meta, blocs d'historique compris.

30 days

Journaux d'exécution conservés pour un numéro géré, avec le texte des messages et des réponses ; le texte des messages lui-même est conservé 30, 90 ou 365 jours, selon votre choix.

Quelle est la différence entre direct et géré ?

Là où Meta livre les webhooks de messages du numéro. En mode géré, affiché comme Via easyCoexistence, Meta livre à easyCoexistence, qui vérifie la signature de Meta, exécute vos automatisations, conserve les chats pour Conversations et, si vous définissez une URL de transfert, transmet chaque modification Meta à votre serveur, signée avec un secret que vous seul détenez. En mode direct, affiché comme Directement vers votre système, easyCoexistence définit votre endpoint HTTPS comme webhook de remplacement sur le WhatsApp Business Account du numéro ; Meta vous envoie donc les données directement, et les messages ne passent jamais par easyCoexistence.

Les webhooks opérationnels, comme account_update et les changements de qualité qui alimentent la supervision, restent chez easyCoexistence dans les deux modes, c'est pourquoi les alertes continuent de fonctionner dans les deux cas.

Managed: Through easyCoexistenceDirect: Straight to your system
Meta delivers toeasyCoexistence, which verifies Meta's signatureYour HTTPS endpoint
AutomationsRun on the numberOff
Your copyOptional Forward URL, one Meta change per POSTMeta's envelope, unchanged
Proof it is genuineX-EC-Signature, HMAC-SHA256 with the number's secretA long random secret in the URL path
Failed deliveries7 attempts over about 33 hoursMeta retries for up to 7 days
History importNot requestedRequested when saved within 24 hours of connecting
Kept by easyCoexistenceMessage text 30, 90 or 365 days, run logs 30 daysNothing

Comment faire passer un numéro d'un mode à l'autre ?

Sur la page du numéro, la carte Où vont les messages entrants affiche le mode sous forme de deux choix, Via easyCoexistence et Directement vers votre système. Enregistrer une destination de webhook, dans la carte Acheminer les messages entrants vers votre propre webhook ou avec set_webhook_destination, passe le numéro en direct. Choisir Via easyCoexistence supprime immédiatement cette destination chez Meta ; ajoutez donc la même URL comme URL de transfert pour continuer à recevoir. Les transferts en file d'attente sont abandonnés quand un numéro quitte le mode géré, et les numéros connectés sans URL de webhook commencent en mode géré.

Depuis votre IA, set_inbound_mode change le mode et définit le transfert en un seul appel, et renvoie le secret de transfert une seule fois :

set_inbound_mode: arguments and result
// set_inbound_mode arguments
{
  "connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "mode": "managed",
  "forward_url": "https://agent.example.com/ec/forward"
}

// result: forward_secret is shown once
{
  "connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "mode": "managed",
  "forward_url": "https://agent.example.com/ec/forward",
  "forward_secret": "whsec_Qm9vbXRoZXNlY3JldHNhcmVmYWtlMTIz",
  "secret_note": "Shown once. Verify X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with it; the body's value is Meta's original payload.",
  "direct_destination": null
}

Que contient un POST transféré ?

Une modification Meta par requête, enveloppée, au lieu de l'enveloppe object, entry et changes de Meta. id est l'identifiant de la livraison, repris dans X-EC-Delivery et stable entre les relances. event est le nom du champ Meta, messages, smb_message_echoes, history ou smb_app_state_sync, repris dans X-EC-Event. received_at correspond au moment où easyCoexistence a reçu la modification de Meta, connection identifie le numéro, et value est exactement ce que Meta a envoyé, de sorte que le code qui lit le payload de Meta fonctionne tel quel. Les statuts de livraison arrivent dans les événements messages, sous value.statuses.

A forwarded messages event: headers and body
POST /ec/forward HTTP/1.1
Content-Type: application/json
User-Agent: easyCoexistence-forward/1
X-EC-Event: messages
X-EC-Delivery: 8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13
X-EC-Signature: t=1794405732,v1=<64 hex characters>

{
  "id": "8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13",
  "event": "messages",
  "received_at": "2026-11-11T14:02:11.482Z",
  "connection": {
    "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
    "phone": "+1 631-555-0142",
    "phone_number_id": "106540352242922",
    "waba_id": "102290129340398",
    "external_ref": null
  },
  "value": {
    "messaging_product": "whatsapp",
    "metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
    "contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
    "messages": [{
      "from": "5511987654321",
      "from_user_id": "BR.13491208655302741918",
      "id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
      "timestamp": "1794405731",
      "type": "text",
      "text": { "body": "Do you deliver on Sundays?" }
    }]
  }
}

Comment vérifier X-EC-Signature en Node.js ?

Lisez l'en-tête comme t=<unix seconds>,v1=<64 hex characters>. Rejetez un t qui s'écarte de plus de 5 minutes de votre horloge, calculez un HMAC-SHA256 sur t, un point et le corps brut, avec pour clé le secret de transfert complet en texte UTF-8, puis comparez le résultat à v1 en temps constant. Ce n'est qu'alors que vous analysez le JSON. Répondez 2xx dans les 10 secondes et faites le travail ensuite, et gardez en mémoire les identifiants de livraison acceptés pour qu'une relance ne soit pas traitée deux fois.

forward-receiver.mjs (Node.js, no dependencies)
// forward-receiver.mjs: node forward-receiver.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";

const SECRET = process.env.EC_FORWARD_SECRET; // the whole whsec_... string is the HMAC key
const taken = new Set(); // delivery ids already accepted: use a database in production

export function verifyEcSignature(raw, header, secret = SECRET, maxAgeSec = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
  if (!m || !secret) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > maxAgeSec) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
  return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}

http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    const raw = Buffer.concat(chunks);
    if (req.method !== "POST" || !verifyEcSignature(raw, req.headers["x-ec-signature"])) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(200).end(); // a 2xx within 10 s, before any work
    const d = JSON.parse(raw.toString("utf8"));
    if (taken.has(d.id)) return; // a retry of a delivery already accepted
    taken.add(d.id);
    // d.event is the Meta field (messages, smb_message_echoes, history, smb_app_state_sync)
    // d.value is Meta's change value, unchanged; queue it for your worker here.
    console.log(d.event, d.connection.phone_number_id, Object.keys(d.value));
  });
}).listen(process.env.PORT ?? 3000);

Comment vérifier la signature en Python ?

Les mêmes quatre vérifications avec la bibliothèque standard : un motif strict pour l'en-tête, l'âge de t, hmac.new sur t, un point et les octets bruts, puis hmac.compare_digest. Avec FastAPI, le corps brut vient de await request.body(), et BackgroundTasks exécute le travail après l'envoi du 200. Avec Flask, utilisez request.get_data(), et ne reconstruisez jamais le corps avec json.dumps, car les séparateurs par défaut de Python ajoutent des espaces et la signature ne correspond plus.

forward_receiver.py (FastAPI)
# forward_receiver.py: pip install fastapi uvicorn, then uvicorn forward_receiver:app
import hashlib, hmac, json, os, re, time
from fastapi import BackgroundTasks, FastAPI, Request, Response

app = FastAPI()
SECRET = os.environ["EC_FORWARD_SECRET"].encode()  # the whole whsec_... string, as bytes
SIGNATURE = re.compile(r"t=([0-9]+),v1=([0-9a-f]{64})")
taken = set()  # delivery ids already accepted: use a database in production

def verify_ec_signature(raw: bytes, header: str, max_age: int = 300) -> bool:
    m = SIGNATURE.fullmatch(header.strip())
    if not m or abs(int(time.time()) - int(m[1])) > max_age:
        return False
    mac = hmac.new(SECRET, m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, m[2])

def process(delivery: dict) -> None:
    if delivery["id"] in taken:  # a retry of a delivery already accepted
        return
    taken.add(delivery["id"])
    print(delivery["event"], delivery["connection"]["phone_number_id"], list(delivery["value"]))

@app.post("/ec/forward")
async def forward(request: Request, tasks: BackgroundTasks):
    raw = await request.body()
    if not verify_ec_signature(raw, request.headers.get("x-ec-signature", "")):
        return Response(status_code=401)
    tasks.add_task(process, json.loads(raw))  # runs after the 200 goes out
    return Response(status_code=200)

Comment les livraisons en échec sont-elles relancées ?

Un transfert est compté comme livré quand votre endpoint répond 2xx, quel qu'il soit, dans les 10 secondes. Tout le reste, un délai dépassé, un 4xx, un 5xx ou une redirection, qui n'est pas suivie, planifie la tentative suivante environ 1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures et 24 heures plus tard, et après la septième tentative la livraison est abandonnée. Chaque tentative est signée à nouveau avec un nouveau t, et l'URL doit être en HTTPS public, vérifié à l'enregistrement puis avant chaque envoi. Les livraisons partent de la plus ancienne à la plus récente, mais une livraison relancée peut arriver après les suivantes ; triez donc selon les horodatages de Meta.

Sur une destination directe, c'est Meta qui relance : tout ce qui n'est pas un HTTP 200 est relancé à fréquence décroissante pendant 7 jours au maximum, et ces relances peuvent répéter un message. Dédoublonnez sur l'identifiant de message de Meta dans les deux modes, car une modification que Meta renvoie est transférée à nouveau sous un nouvel identifiant de livraison.

Comment un endpoint direct sait-il qu'un POST est authentique ?

Pas grâce à X-Hub-Signature-256. Meta signe avec le secret d'application de l'app qui possède l'abonnement, celui d'easyCoexistence pour un numéro connecté ici, qui n'est pas partagé ; vérifier cet en-tête avec le secret de votre propre app Meta rejette donc des livraisons authentiques. Le verify token ne prouve l'endpoint qu'une seule fois, pendant le handshake GET de Meta. Voici ce qui fonctionne à la place :

  • Mettez 32 caractères aléatoires ou plus dans le chemin de l'URL de rappel et rejetez les requêtes qui n'en ont pas ; pour changer, enregistrez une nouvelle URL.
  • Utilisez un récepteur générique, comme le nœud Webhook de n8n, et non un déclencheur WhatsApp qui attend votre propre app Meta.
  • Téléchargez les médias par identifiant auprès de Meta avec le token du numéro, de sorte qu'un identifiant falsifié échoue simplement.
  • Sur des serveurs auto-hébergés, vous pouvez autoriser uniquement le réseau de Meta, les routes annoncées par AS32934.
  • Ou passez en géré avec une URL de transfert, où X-EC-Signature prouve chaque POST.

Erreurs courantes

  • Brancher sur l'URL de transfert du code écrit pour l'enveloppe de Meta, sans rien changer. Un transfert transporte une seule modification : lisez event et value, pas object, entry et changes.
  • Attendre un X-EC-Event de statuses. Les statuts de livraison arrivent dans les événements messages, sous value.statuses, et les réponses saisies dans l'app arrivent en smb_message_echoes.
  • Traiter avant de répondre. Un transfert attend 10 secondes, puis la même livraison revient avec un nouveau t ; répondez 2xx d'abord et traitez depuis une file d'attente.
  • Passer en géré en supposant que l'ancienne URL reçoit encore. La destination directe est supprimée à cet instant ; transmettez forward_url dans le même appel set_inbound_mode.
Faire cela avec EasyCoexistence

easyCoexistence connecte un numéro de l'app WhatsApp Business à la Cloud API de Meta via Coexistence et vous laisse choisir, pour chaque numéro, où vont ses messages : directement de Meta vers votre serveur, ou via easyCoexistence pour que les automatisations puissent répondre et qu'une copie signée arrive à votre URL de transfert. La supervision et les alertes fonctionnent dans les deux modes. De US$ 9 à US$ 0,75 par numéro et par mois, en baisse à mesure que vous ajoutez des numéros, avec 3 jours d'essai gratuit.

Questions fréquemment posées

Mon serveur verra-t-il ce qu'une automatisation a répondu ?

Non, pas le texte. Meta signale les envois de l'API (sent, delivered, read) sous forme de statuts dans les événements messages, avec l'identifiant du message ; le texte lui-même figure dans le journal d'exécution de l'automatisation, conservé 30 jours dans l'onglet Runs, et dans Conversations pendant la durée que vous avez choisie.

Comment renouveler le secret de transfert ?

Cliquez sur Nouveau secret sur la page du numéro, ou appelez set_inbound_mode avec rotate_secret à true. Le nouveau secret s'affiche une seule fois et signe tout à partir de là, y compris les relances des anciennes livraisons ; mettez donc votre serveur à jour immédiatement.

Une URL de transfert demande-t-elle le handshake GET de Meta ?

Non. Seule une destination directe est appelée par Meta et doit renvoyer hub.challenge. Une URL de transfert est appelée par easyCoexistence et ne reçoit que des POST signés.

Un numéro peut-il avoir à la fois une destination directe et une URL de transfert ?

Non. Une URL de transfert ne fonctionne que tant que le numéro est géré, et enregistrer une destination directe le passe en direct. L'URL de transfert et son secret sont conservés, donc repasser en géré reprend le transfert.

Poursuivre la lecture

Prêt à commencer ?

Configurez WhatsApp Coexistence en quelques minutes, pas en quelques mois. L’application continue de fonctionner sur le téléphone.

Commencer l'essai gratuit

Vérifié le