Documentation

Webhooks entrants

Recevez en temps réel les réponses de votre numéro WhatsApp connecté. Compatible drop-in avec TextMeBot — les intégrations existantes qui traitent type / from / from_name / to / file / message fonctionnent sans modification.

1. Configurer l'endpoint

Ouvrez /admin/webhook dans le portail client :

  1. Collez votre URL HTTPS publique.
  2. Cliquez sur Enregistrer — un secret HMAC de 64 caractères est généré automatiquement. Copiez-le immédiatement, il sera ensuite masqué.
  3. Cliquez sur Test fire pour envoyer un payload d'exemple vers votre endpoint.

2. Payload (compatible TextMeBot)

Pour chaque message entrant, TextMeFlow effectue un POST avec le content-type application/json et ce corps :

{
  "type": "text",
  "from": "32472932208",
  "from_name": "Jan Janssens",
  "to": "32499123456",
  "file": "null",
  "message": "Bedankt voor de bevestiging!",
  "from_me": false,
  "wa_message_id": "3EB0A1B2C3D4E5F6",
  "message_id": null
}
ChampTypeContenu
typestringtext, image, audio, video, document ou location
fromstringExpéditeur, chiffres uniquement (pas de +)
from_namestringpushName WhatsApp, peut être vide
tostringVotre numéro connecté, chiffres uniquement
filestringPour les messages texte, littéralement la chaîne "null" (identique à TextMeBot). Pour image, video, audio et document, l'URL du fichier, hébergé par TextMeFlow. Une photo sans légende arrive avec un message vide.
messagestringTexte ou légende ; pour document le nom de fichier, pour location la chaîne "lat,lng"
from_mebooleantrue pour un message que vous avez envoyé — via l'API ou à la main dans WhatsApp. Votre système voit ainsi la conversation complète. Si true, from est votre numéro et to celui du client.
wa_message_idstringL'identifiant WhatsApp du message, dans les deux sens. Unique par message ; utilisable comme clé de dédoublonnage.
message_idstring | nullUniquement avec from_me: true et envoyé via l'API : le message_id reçu lors de l'envoi. C'est ainsi que vous reconnaissez votre propre envoi et évitez de le stocker deux fois. null pour les messages tapés à la main et pour tout ce qui arrive.

3. En-têtes

En-têteContenu
Content-Typeapplication/json
User-AgentTextMeFlow-Webhook/1.0
X-TextMeFlow-Event-IdUUID par message — utilisez-le comme clé d'idempotence, les retries réutilisent le même id.
X-TextMeFlow-Signaturesha256=<hex> — HMAC-SHA256 du corps brut avec votre secret webhook.
X-TextMeFlow-DeliveryUUID par tentative de livraison, pratique pour grep les logs.

4. Vérifier la signature

Calculez le HMAC-SHA256 sur le corps brut de la requête (pas sur un objet parsé — les différences d'encodeur JSON casseraient votre hash) et comparez en temps constant avec la valeur sha256=… de l'en-tête.

PHP

// $secret = 'tmf_…' uit /admin/webhook
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
$received = $_SERVER['HTTP_X_TEXTMEFLOW_SIGNATURE'] ?? '';

if (! hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}
$body = json_decode($raw, true);

Node.js (Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();
// Capture raw body for HMAC; can't run after express.json() ate it.
app.use(express.raw({ type: 'application/json' }));

app.post('/textmeflow-inbound', (req, res) => {
  const raw = req.body; // Buffer
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.TMF_WEBHOOK_SECRET)
    .update(raw)
    .digest('hex');

  const received = req.get('X-TextMeFlow-Signature') ?? '';
  if (
    expected.length !== received.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))
  ) {
    return res.sendStatus(401);
  }

  const body = JSON.parse(raw.toString('utf8'));
  // …handle body…
  res.sendStatus(200);
});

Python (Flask)

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ['TMF_WEBHOOK_SECRET'].encode()

@app.post('/textmeflow-inbound')
def inbound():
    raw = request.get_data()
    expected = 'sha256=' + hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    received = request.headers.get('X-TextMeFlow-Signature', '')
    if not hmac.compare_digest(expected, received):
        abort(401)
    body = request.get_json()
    # …handle body…
    return '', 200

5. Politique de retry

Une livraison est réussie pour toute réponse 2xx sous 10 s. Autres résultats :

RéponseComportement
2xx livré, pas de retry.
408 / 429 / 5xx retry — max 5 fois avec backoff 1m, 5m, 30m, 2h, 6h.
autres 4xx échec, pas de retry. Un 401 signifie généralement que votre secret ne correspond plus — vérifiez et corrigez de votre côté.
timeout / réseau retry comme 5xx.

Après 6 tentatives au total (première + 5 retries), la livraison est marquée failed. Le statut de chaque tentative est visible dans /admin/webhook.

6. Migrer depuis TextMeBot

Aucune modification de code nécessaire — le format du payload est identique. Une seule action :

  1. Collez l'URL de votre endpoint TextMeBot existant dans /admin/webhook.
  2. Ajoutez une vérification de signature (TextMeBot n'en a pas — mise à niveau obligatoire pour la production). Voir les snippets ci-dessus.

Prêt à recevoir ?

Configurez votre endpoint dans /admin/webhook et envoyez un payload de test en un clic.