InloggenGratis proefperiode starten
easyCoexistence Officiële API's

Zo ontvang je de WhatsApp-berichten en reacties op social media van je klanten via een webhook

Elke verbinding krijgt een eigen webhook voor de WhatsApp-berichten of social-reacties van je klanten via de Partner API van easyCoexistence. WhatsApp-berichten gaan van Meta rechtstreeks naar die URL, ondertekend met het geheim van de Tech Provider-app in plaats van een geheim dat jij bezit. Een lang willekeurig geheim in het URL-pad authenticeert ze dus. Instagram- en Facebook-reacties en -DM's, en TikTok-reacties, worden doorgestuurd zodra ze binnenkomen, per account ondertekend met X-EC-Signature.

200 characters

De maximale lengte die Meta toestaat voor de alternatieve callback-URL die de berichten van een nummer naar je endpoint stuurt.

7 days

Hoe lang Meta een WhatsApp-webhook opnieuw probeert te versturen die je endpoint niet heeft geaccepteerd, met steeds minder frequentie, wat tot duplicaten kan leiden.

AS32934

Het netwerk van Meta; whois-routeopzoekingen daarvoor tonen de adressen waarvandaan WhatsApp-webhooks komen, die Meta periodiek wijzigt.

3 MB

De grootste omvang die een WhatsApp-webhook-payload volgens Meta kan hebben.

5 minutes

Leeftijd waarna een doorgestuurde gebeurtenis met getekende timestamp moet worden geweigerd, waarbij de HMAC in constante tijd wordt vergeleken.

Hoe krijgt elke verbinding een eigen bestemming?

Via één aanroep per resource. Een WhatsApp-nummer gebruikt PUT /connections/{id}/webhook met een url en een verify_token, of hetzelfde paar als webhook_url en webhook_verify_token in de connect-sessie, zodat het nummer vanaf de eerste minuut naar jou wordt doorgestuurd. Een social-account gebruikt PUT /channels/{id}/webhook zodra het is verbonden. Een url van null bij beide zet de levering uit. De twee paden verschillen in wie levert en hoe je authenticeert:

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

Hoe stuur je de berichten van een nummer naar je endpoint?

Geef het een HTTPS-URL waarvan het pad een lang willekeurig geheim bevat, plus een verify token: webhook_verify_token op een connect-sessie, 8 tot 200 tekens, of verify_token bij de PUT. Meta controleert de URL direct met een GET met hub.mode=subscribe, hub.verify_token en hub.challenge. Je endpoint moet met de waarde van hub.challenge antwoorden wanneer de token overeenkomt. Mislukt die handshake, dan geeft de PUT 502 meta_rejected terug met de eigen melding van Meta. Bij een connect-sessie verbindt het nummer wel, en het veld last_error van de sessie zegt waarom de URL niet is toegepast.

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

Waarom kun je Meta's handtekening niet controleren, en wat komt ervoor in de plaats?

Meta ondertekent elke levering met X-Hub-Signature-256, een HMAC-SHA256 van de payload, gesleuteld met de App Secret van de ontvangende app. Voor de nummers van je klanten is die app de Tech Provider-app van easyCoexistence. Het geheim daarvan wordt nooit gedeeld, dus de header kan aan jouw kant niet worden geverifieerd. Het lange willekeurige geheim in het URL-pad dient in plaats daarvan als authenticatie: vergelijk het in constante tijd en weiger al het andere. Als tweede laag sta je alleen de routes toe die bij Meta's AS32934 horen, en vernieuw je die lijst, want Meta wijzigt zijn IP-adressen periodiek.

Welke WhatsApp-webhooks bereiken je URL?

De velden die een alternatieve callback-URL van Meta kan dragen: messages, voor wat klanten sturen en de status van wat jij verstuurt; smb_message_echoes, voor wat het bedrijf verstuurt vanuit de WhatsApp Business-app; en de history en smb_app_state_sync van de eenmalige import. Meta stuurt nooit template-webhooks, of account-webhooks zoals account_update, naar een overschrijving. Die gaan in plaats daarvan naar de callback van easyCoexistence. Daarom wordt de templatebeoordeling via polling uitgelezen, en bereikt een afwijzing je als statusgebeurtenis.

  • De bestemming wordt ingesteld op het WhatsApp Business Account, dus twee nummers in één account delen die: route op value.metadata.phone_number_id.
  • Media komt binnen als ID; haal het bestand bij Meta op met het token van de klant uit de aanroep voor de credentials.
  • Payloads kunnen 3 MB bereiken, dus verhoog elke limiet voor de body-grootte die lager is ingesteld.

Hoe ziet een doorgestuurde social-gebeurtenis eruit?

Een POST met Content-Type application/json en een X-EC-Signature-header, met vier sleutels: platform; account_id, het kanaal-ID dat de Partner API gebruikt; external_id, het ID van het account op het netwerk; en entry. Voor Instagram en Facebook is entry de webhook-entry van Meta ongewijzigd, met changes voor reacties en vermeldingen en messaging voor DM's. Voor TikTok bevat het de comment.update-gebeurtenis met de geparseerde inhoud, en comment_id, video_id en parent_comment_id als strings, zodat 64-bit-ID's niet worden afgerond.

  • Instagram-accounts zijn geabonneerd op reacties, berichten en vermeldingen; Facebook-pagina's op feed, messages en mention; TikTok stuurt comment.update.
  • easyCoexistence ontvangt geen reactiegebeurtenissen van YouTube of LinkedIn: hun PUT antwoordt met 400 not_supported, en hun reacties worden via de API van elk netwerk met de credentials gelezen.
  • Doorgestuurde gebeurtenissen bevatten geen X-EC-Event- of X-EC-Delivery-header, dus dedupliceer op de eigen ID's van het netwerk, zoals een reactie-ID of een message mid.
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>" }
        }
      }
    ]
  }
}

Hoe verifieer je X-EC-Signature, stap voor stap?

Met de signing_secret die PUT /channels/{id}/webhook heeft teruggegeven. Die wordt maar één keer getoond en is uniek voor dat account. De header luidt t=<unix>,v1=<hex>. Doe dan voor elke levering het volgende:

  • Lees de ruwe requestbody als bytes, vóór enige JSON-parsing.
  • Splits de header op komma's in t, een Unix-tijd in seconden, en v1, een hex-digest.
  • Weiger de levering als t meer dan 5 minuten van je klok af ligt.
  • Bereken HMAC-SHA256 over t, een punt en de ruwe body, gesleuteld met het geheim van dat account, als hex.
  • Vergelijk het met v1 in constante tijd, antwoord daarna met 2xx en zet het werk in de wachtrij.
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);
});

Wat gebeurt er als er geen bestemming is ingesteld?

Er komt niets bij je aan, en er wordt niets in de wachtrij gezet om later te verzenden. Een nummer zonder webhook_url valt terug op de callback van easyCoexistence, waar de berichten worden weggegooid zonder opgeslagen te worden. Het krijgt ook geen import van de chatgeschiedenis, die pas wordt aangevraagd zodra er een bestemming bestaat. Een social-account zonder bestemming wordt niet doorgestuurd: de gebeurtenissen bereiken nog wel de app van easyCoexistence, maar er wordt niets voor jou bewaard. Stel elke bestemming in voordat je het verkeer nodig hebt.

Wat gebeurt er met een bestemming wanneer een verbinding wegvalt of wordt verwijderd?

Een nummer behoudt zijn bestemming. Wanneer een weggevallen nummer weer verbinding maakt, zet easyCoexistence jouw URL opnieuw bij Meta, en hetzelfde gebeurt wanneer een geschorst nummer terugkomt. Een social-account verwijderen wist zijn bestemming en zijn geheim. Roep daarom na het opnieuw verbinden PUT /channels/{id}/webhook opnieuw aan en sla het nieuwe geheim op. Die PUT geeft telkens een nieuw geheim uit wanneer hij met een URL wordt aangeroepen, en het oude geheim stopt meteen met ondertekenen.

Zo stel je het in

  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.

Veelgemaakte fouten

  • X-Hub-Signature-256 controleren op de WhatsApp-levering van je klanten. Meta berekent die met de app secret van easyCoexistence, die nooit wordt gedeeld, dus de controle kan nooit slagen. Authenticeer met het geheim in het URL-pad.
  • X-EC-Signature verifiëren over geparseerde JSON. De HMAC dekt de ruwe body byte voor byte, en opnieuw serialiseren verandert de bytes, dus verifieer vóór het parsen.
  • Eén geheim gebruiken voor elk kanaal. Elk social-account ondertekent met een eigen geheim en statusgebeurtenissen met een ander, dus zoek het geheim op via account_id.
  • Trage verwerking doen voordat je een doorgestuurde gebeurtenis beantwoordt. Die wordt één keer verzonden, wacht 8 seconden op je antwoord en wordt nooit opnieuw geprobeerd. Antwoord dus eerst met 2xx en verwerk daarna.
Dit doen met EasyCoexistence

easyCoexistence stuurt de berichten van elk klantnummer rechtstreeks van Meta naar je server. Instagram- en Facebook-reacties en DM's, en TikTok-reacties, worden zodra ze binnenkomen naar je endpoint doorgestuurd, per account ondertekend, zonder kopie te bewaren, en elke verbinding wordt 24/7 bewaakt. US$ 9 tot US$ 0,75 per verbinding per maand, dalend naarmate je verbindingen toevoegt, met de eerste 3 dagen als gratis proefperiode.

Veelgestelde vragen

Kan ik Meta's handtekening controleren op de WhatsApp-berichten van mijn klanten?

Nee. Meta ondertekent ze met het geheim van de Tech Provider-app van easyCoexistence, dat nooit wordt gedeeld. Authenticeer met het lange willekeurige geheim in je URL-pad, en eventueel met de IP-bereiken van Meta.

Sturen YouTube- en LinkedIn-verbindingen reactiegebeurtenissen door?

Nee. easyCoexistence ontvangt van beide geen reactiegebeurtenissen, dus PUT /channels/{id}/webhook antwoordt met 400 not_supported. Lees hun reacties via de API van elk netwerk met de credentials van het kanaal.

Worden doorgestuurde social-gebeurtenissen opnieuw geprobeerd als mijn server uitligt?

Nee. Elke gebeurtenis wordt één keer verzonden en er wordt geen kopie bewaard. WhatsApp-leveringen verschillen, omdat Meta die zelf tot 7 dagen opnieuw probeert.

Gaan berichten via easyCoexistence?

Niet op WhatsApp: Meta levert de berichten van een nummer rechtstreeks aan de webhook die je instelt. Reacties en DM's van de social-netwerken worden naar je endpoint doorgestuurd zodra ze binnenkomen, per account ondertekend, zonder kopie te bewaren.

Lees verder

Koppel je eerste kanaal in twee minuten.

Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.

  • 3 dagen gratis
  • Op elk moment opzegbaar
  • Alleen officiële API's
  • 24/7 bewaakt

Geverifieerd op