Se connecterCommencer l’essai gratuit
easyCoexistence API officielles

Recevoir par webhook les messages WhatsApp et les commentaires sociaux de vos clients

Chaque connexion reçoit son propre webhook pour les messages WhatsApp de vos clients ou leurs commentaires sur les réseaux sociaux, via la Partner API d'easyCoexistence. Les messages WhatsApp vont directement de Meta vers cette URL, signés avec le secret de l'application Tech Provider et non avec un secret que vous détenez : un secret aléatoire long dans le chemin de l'URL les authentifie donc. Les commentaires et DM Instagram et Facebook, ainsi que les commentaires TikTok, sont transmis dès leur arrivée, signés par compte avec X-EC-Signature.

200 characters

Longueur maximale, selon Meta, de l'URL de rappel alternative qui envoie les messages d'un numéro vers votre endpoint.

7 days

Durée pendant laquelle Meta renouvelle la livraison d'un webhook WhatsApp que votre endpoint n'a pas accepté, à fréquence décroissante, ce qui peut produire des doublons.

AS32934

Le réseau de Meta : les recherches de route whois sur celui-ci listent les adresses d'où viennent les webhooks WhatsApp, que Meta modifie périodiquement.

3 MB

La taille maximale d'un payload de webhook WhatsApp, selon Meta.

5 minutes

Âge au-delà duquel un horodatage signé d'un événement transmis doit être rejeté, la signature HMAC étant comparée à temps constant.

Comment chaque connexion obtient-elle sa propre destination ?

Chaque ressource s'obtient par un seul appel. Un numéro WhatsApp prend PUT /connections/{id}/webhook avec une url et un verify_token, ou la même paire sous les noms webhook_url et webhook_verify_token sur sa session de connexion, afin que le numéro vous soit routé dès sa première minute. Un compte social prend PUT /channels/{id}/webhook une fois connecté. Une url à null sur l'un ou l'autre désactive la livraison. Les deux chemins diffèrent par qui livre et par la manière de vous authentifier :

WhatsApp numberInstagram, Facebook, TikTok
Set withwebhook_url on the session, or PUT /connections/{id}/webhookPUT /channels/{id}/webhook, after it connects
Delivered byMeta, straight to your URLeasyCoexistence, forwarding each event as it arrives
BodyMeta's webhook, unchangedplatform, account_id, external_id and the network's entry
AuthenticateA long random secret in the URL pathX-EC-Signature, keyed with the account's secret
RetriesMeta's own, for up to 7 daysNone: one attempt
Copy keptNoneNone

Comment faire pointer les messages d'un numéro vers votre endpoint ?

Indiquez une URL HTTPS dont le chemin contient un secret aléatoire long, ainsi qu'un token de vérification : webhook_verify_token sur une session de connexion, de 8 à 200 caractères, ou verify_token sur le PUT. Meta vérifie aussitôt l'URL par un GET portant hub.mode=subscribe, hub.verify_token et hub.challenge ; votre endpoint doit répondre avec la valeur de hub.challenge lorsque le token correspond. Si cette vérification échoue, le PUT renvoie 502 meta_rejected avec le message propre à Meta. Sur une session de connexion, le numéro se connecte tout de même, et le last_error de la session indique pourquoi l'URL n'a pas été appliquée.

Node.js: Meta's handshake and the path secret
import express from "express";
import { timingSafeEqual } from "node:crypto";

const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();

function same(a, b) {
  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
  return x.length === y.length && timingSafeEqual(x, y);
}

// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
    return res.sendStatus(403);
  }
  res.send(req.query["hub.challenge"]);
});

// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  res.sendStatus(200); // answer first: Meta retries for up to 7 days
  enqueue(req.body); // deduplicate on each message id before acting
});

Pourquoi ne pouvez-vous pas vérifier la signature de Meta, et par quoi est-elle remplacée ?

Meta signe chaque livraison avec X-Hub-Signature-256, un HMAC-SHA256 du payload calculé avec l'App Secret de l'application réceptrice. Pour les numéros de vos clients, cette application est l'application Tech Provider d'easyCoexistence, dont le secret n'est jamais partagé : l'en-tête ne peut donc pas être vérifié de votre côté. Le secret aléatoire long dans le chemin de l'URL sert alors de justificatif : comparez-le à temps constant et refusez tout le reste. En second niveau, placez sur liste blanche les routes enregistrées auprès de Meta sous l'AS32934 et actualisez cette liste, car Meta modifie périodiquement ses adresses IP.

Quels webhooks WhatsApp atteignent votre URL ?

Les champs qu'une URL de rappel alternative peut porter chez Meta : messages, pour ce que les clients envoient et le statut de ce que vous envoyez ; smb_message_echoes, pour ce que l'entreprise envoie depuis l'application WhatsApp Business ; et l'historique de l'import unique ainsi que smb_app_state_sync. Meta n'envoie jamais à une surcharge les webhooks de template, ni les webhooks de compte tels que account_update. Ils atteignent à la place le callback d'easyCoexistence, c'est pourquoi l'examen des templates se fait par interrogation et qu'un rejet vous parvient sous forme d'événement de statut.

  • La destination est définie sur le compte WhatsApp Business, donc deux numéros d'un même compte la partagent : routez sur value.metadata.phone_number_id.
  • Les médias arrivent sous forme d'identifiant ; récupérez le fichier auprès de Meta avec le token du client issu de l'appel d'identifiants.
  • Les payloads peuvent atteindre 3 Mo : relevez toute limite de taille du corps fixée en dessous.

À quoi ressemble un événement social transmis ?

Un POST avec Content-Type application/json et un en-tête X-EC-Signature, portant quatre clés : platform ; account_id, l'ID de canal qu'utilise la Partner API ; external_id, l'ID du compte sur le réseau ; et entry. Pour Instagram et Facebook, entry est l'entrée de webhook de Meta sans modification, avec changes pour les commentaires et les mentions, et messaging pour les DM. Pour TikTok, elle contient l'événement comment.update avec son contenu analysé, et comment_id, video_id et parent_comment_id sous forme de chaînes, afin que les ID sur 64 bits ne soient pas arrondis.

  • Les comptes Instagram sont abonnés aux commentaires, aux messages et aux mentions ; les Pages Facebook au feed, aux messages et aux mentions ; TikTok envoie comment.update.
  • easyCoexistence ne reçoit aucun événement de commentaire de YouTube ni de LinkedIn : leur PUT répond 400 not_supported, et leurs commentaires se lisent via l'API de chaque réseau avec les identifiants.
  • Les transmissions ne portent ni en-tête X-EC-Event ni X-EC-Delivery : dédupliquez donc sur les identifiants propres au réseau, comme l'ID d'un commentaire ou le mid d'un message.
A forwarded Instagram comment
{
  "platform": "instagram",
  "account_id": "<CHANNEL_ID>",
  "external_id": "<INSTAGRAM_ACCOUNT_ID>",
  "entry": {
    "id": "<INSTAGRAM_ACCOUNT_ID>",
    "time": 1793440800,
    "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 X-EC-Signature, étape par étape ?

Avec le signing_secret renvoyé par PUT /channels/{id}/webhook, affiché une seule fois et propre à ce compte. L'en-tête se présente ainsi : t=<unix>,v1=<hex>. Puis, pour chaque livraison :

  • Lisez le corps brut de la requête comme des octets, avant toute analyse JSON.
  • Découpez l'en-tête sur les virgules pour obtenir t, une heure Unix en secondes, et v1, un condensé hexadécimal.
  • Rejetez la livraison si t s'écarte de plus de 5 minutes de votre horloge.
  • Calculez le HMAC-SHA256 de t, d'un point et du corps brut, avec le secret propre à ce compte, en hexadécimal.
  • Comparez-le à v1 à temps constant, puis répondez 2xx et mettez le travail en file d'attente.
Node.js: verifying a forwarded event
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database

app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries(
    (req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
  );
  if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
    return res.sendStatus(401); // missing or stale timestamp
  }
  let event;
  try {
    event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
  } catch {
    return res.sendStatus(400);
  }
  const secret = secrets.get(event.account_id);
  if (!secret || !sig.v1) return res.sendStatus(401);
  const expected = createHmac("sha256", secret)
    .update(sig.t + ".")
    .update(req.body) // the raw bytes, exactly as they arrived
    .digest("hex");
  if (expected.length !== sig.v1.length ||
      !timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
    return res.sendStatus(401);
  }
  res.sendStatus(204); // one attempt and no retries: acknowledge, then work
  enqueue(event);
});

Que se passe-t-il lorsqu'aucune destination n'est définie ?

Rien ne vous parvient, et rien n'attend d'être envoyé plus tard. Un numéro sans webhook_url revient au callback d'easyCoexistence, où ses messages sont abandonnés sans être stockés, et il ne bénéficie d'aucun import d'historique de conversation, qui n'est demandé qu'une fois une destination existante. Un compte social sans destination n'est pas transmis : ses événements parviennent tout de même à l'application d'easyCoexistence, mais aucun n'est conservé pour vous. Définissez chaque destination avant d'en avoir besoin.

Que devient une destination lorsqu'une connexion tombe ou est supprimée ?

Un numéro conserve sa destination. Lorsqu'un numéro interrompu se reconnecte, easyCoexistence retransmet votre URL à Meta, et il en va de même lorsqu'un numéro suspendu revient. La suppression d'un compte social efface sa destination et son secret : après sa reconnexion, rappelez PUT /channels/{id}/webhook et conservez le nouveau secret. Ce PUT émet un nouveau secret chaque fois qu'il est appelé avec une URL, et l'ancien cesse aussitôt de signer.

Comment le configurer

  1. Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
  2. Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
  3. Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
  4. Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.

Erreurs courantes

  • Vérifier X-Hub-Signature-256 sur les livraisons WhatsApp de vos clients. Meta la calcule avec le secret de l'application d'easyCoexistence, qui n'est jamais partagé : la vérification ne peut donc pas réussir. Authentifiez avec le secret du chemin de l'URL.
  • Vérifier X-EC-Signature sur du JSON déjà analysé. Le HMAC couvre le corps brut octet par octet, et le resérialiser modifie les octets : vérifiez donc avant l'analyse.
  • Utiliser un seul secret pour tous les canaux. Chaque compte social signe avec son propre secret, et les événements de statut avec un autre ; recherchez donc le secret par account_id.
  • Effectuer un travail lent avant de répondre à un événement transmis. Il est envoyé une seule fois, attend 8 secondes votre réponse et n'est jamais relancé : répondez donc 2xx d'abord, puis traitez.
Faire cela avec EasyCoexistence

easyCoexistence achemine les messages de chaque numéro client depuis Meta directement vers votre serveur. Il transmet à votre endpoint, dès leur arrivée et signés par compte, les commentaires et DM Instagram et Facebook ainsi que les commentaires TikTok, sans aucune copie conservée et avec chaque connexion surveillée 24/7. 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

Puis-je vérifier la signature de Meta sur les messages WhatsApp de mes clients ?

Non. Meta les signe avec le secret de l'application Tech Provider d'easyCoexistence, qui n'est jamais partagé. Authentifiez avec le secret aléatoire long dans le chemin de votre URL, et éventuellement avec les plages IP de Meta.

Les connexions YouTube et LinkedIn transmettent-elles les événements de commentaire ?

Non. easyCoexistence ne reçoit aucun événement de commentaire de l'un ni de l'autre, donc PUT /channels/{id}/webhook répond 400 not_supported. Lisez leurs commentaires via l'API de chaque réseau avec les identifiants du canal.

Les événements sociaux transmis sont-ils relancés si mon serveur est en panne ?

Non. Chacun est envoyé une seule fois et aucune copie n'est conservée. Les livraisons WhatsApp diffèrent, car Meta les relance lui-même pendant 7 jours au plus.

Les messages transitent-ils par easyCoexistence ?

Pas sur WhatsApp : Meta livre les messages d'un numéro directement au webhook que vous avez défini. Les commentaires et DM des réseaux sociaux vous sont transmis sur votre endpoint dès leur arrivée, signés par compte, sans copie conservée.

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