Welke WhatsApp-webhookevents stuurt TextMeFlow? Een overzicht

Je hebt een webhook-URL ingesteld en TextMeFlow stuurt data naar je server — maar welke events precies, en wat zit er in elke payload? Dit overzicht helpt je bepalen welke events je moet afvangen en welke je kan negeren.

Waarom events (en niet alleen "bericht binnen")

De meeste integraties denken enkel aan inkomende berichten, maar een WhatsApp-koppeling genereert meer signalen dan dat: leveringsstatus, sessiestatus van het gekoppelde toestel, en foutmeldingen. Als je alleen op inkomende berichten reageert, mis je bijvoorbeeld dat je nummer de verbinding is kwijtgeraakt en dat uitgaande berichten al een tijdje niet meer aankomen.

Elke webhookcall is een POST met een JSON-body en een event-veld dat het type aangeeft. Voor het correct verifiëren van de HMAC-handtekening op elke call, zie onze aparte gids over webhook-signatures verifiëren — dit artikel focust op de events zelf.

message.received

Het meest gebruikte event: iemand stuurt een WhatsApp-bericht naar je gekoppelde nummer. De payload bevat het afzendernummer, het berichttype (tekst, afbeelding, document, locatie, …), de inhoud of media-URL, en een timestamp. Dit is het event waarop je chatbots, auto-replies en ticket-routing bouwt.

Let op: media (foto's, PDF's, spraakberichten) komt niet inline in de payload, maar als een tijdelijke download-URL. Haal het bestand meteen op — de URL is niet oneindig geldig.

message.delivered en message.read

Voor uitgaande berichten die je zelf via de API verstuurde, krijg je statusupdates terug:

• message.delivered — het bericht is toegekomen op het toestel van de ontvanger.
• message.read — de ontvanger heeft het bericht geopend (blauw vinkje), voor zover die functie niet uitstaat aan hun kant.

Deze events zijn ideaal om leveringsdashboards te bouwen of om te detecteren dat een bepaald nummer systematisch niet bereikt wordt — vaak een teken van een verkeerd/afgesloten nummer, niet van een probleem bij jou.

message.failed

Een uitgaand bericht kon niet afgeleverd worden. De payload bevat een foutcode en -omschrijving. Meestal gaat het om een ongeldig of niet-WhatsApp-nummer, een ontvanger die je geblokkeerd heeft, of een tijdelijke leveringsfout bij WhatsApp zelf. Bouw hier retry-logica op met mate: blind opnieuw versturen na een failed verhoogt je risicoscore in de anti-spam pipeline.

session.connected en session.disconnected

Deze twee events gaan niet over berichten, maar over de status van het gekoppelde WhatsApp-toestel zelf:

• session.connected — het toestel is (opnieuw) gekoppeld en actief. Dit event vuurt ook af bij een herverbinding, niet enkel bij de eerste koppeling.
• session.disconnected — de koppeling is verbroken (toestel offline, WhatsApp uitgelogd, netwerkprobleem). Vanaf dit moment worden geen berichten meer verstuurd of ontvangen tot herkoppeling.

Voor elke productieomgeving is het aan te raden om op session.disconnected een alert te sturen (Slack, e-mail, monitoring-tool) — dit is het event dat je het snelst wil weten, want zonder actieve sessie ligt je hele WhatsApp-kanaal stil.

Praktisch: één endpoint, één switch

De meeste teams verwerken alle events op één webhook-endpoint en routeren intern op het event-veld:

app.post('/webhooks/textmeflow', (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case 'message.received':
      handleIncoming(data);
      break;
    case 'message.delivered':
    case 'message.read':
      updateDeliveryStatus(data);
      break;
    case 'message.failed':
      logFailure(data);
      break;
    case 'session.disconnected':
      alertTeam(data);
      break;
  }

  res.sendStatus(200);
});

Antwoord altijd snel met een 2xx-status, ook als je verwerking asynchroon gebeurt — anders interpreteert TextMeFlow de call als mislukt en volgt een retry, wat tot dubbele verwerking kan leiden als je niet idempotent werkt.

Aan de slag

Stel je webhook-URL in via het dashboard en test met een bericht naar jezelf: je ziet meteen message.received binnenkomen, gevolgd door message.delivered zodra WhatsApp het bevestigt. Nog geen account? Start gratis met 50 berichten per maand, voor altijd — meld je hier aan.