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 :
- Collez votre URL HTTPS publique.
- Cliquez sur Enregistrer — un secret HMAC de 64 caractères est généré automatiquement. Copiez-le immédiatement, il sera ensuite masqué.
- 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
}
| Champ | Type | Contenu |
|---|---|---|
| type | string | text, image, audio, video, document ou location |
| from | string | Expéditeur, chiffres uniquement (pas de +) |
| from_name | string | pushName WhatsApp, peut être vide |
| to | string | Votre numéro connecté, chiffres uniquement |
| file | string | Pour 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. |
| message | string | Texte ou légende ; pour document le nom de fichier, pour location la chaîne "lat,lng" |
| from_me | boolean | true 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_id | string | L'identifiant WhatsApp du message, dans les deux sens. Unique par message ; utilisable comme clé de dédoublonnage. |
| message_id | string | null | Uniquement 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ête | Contenu |
|---|---|
| Content-Type | application/json |
| User-Agent | TextMeFlow-Webhook/1.0 |
| X-TextMeFlow-Event-Id | UUID par message — utilisez-le comme clé d'idempotence, les retries réutilisent le même id. |
| X-TextMeFlow-Signature | sha256=<hex> — HMAC-SHA256 du corps brut avec votre secret webhook. |
| X-TextMeFlow-Delivery | UUID 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éponse | Comportement |
|---|---|
| 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 :
- Collez l'URL de votre endpoint TextMeBot existant dans /admin/webhook.
- 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.