· 6 min · TextMeFlow Team

Vérifier les signatures des webhooks WhatsApp (HMAC)

Chaque réponse WhatsApp que votre client envoie est transmise à votre serveur sous forme de webhook. C'est pratique — pas d'interrogation répétée, livraison quasi instantanée — mais cela signifie aussi que votre point de terminaison est une URL publique sur laquelle n'importe qui sur Internet peut envoyer un POST. Si vous ne vérifiez pas que la requête provient bien de TextMeFlow, un attaquant (ou simplement un robot curieux) peut injecter de fausses « réponses de clients » directement dans votre système. Voici comment procéder correctement, avec les deux erreurs qui cassent discrètement les vérifications de signature en production.

Comment TextMeFlow signe les webhooks

Chaque livraison comprend un en-tête X-TextMeFlow-Signature de la forme sha256=<hex>, qui est un condensat HMAC-SHA256 du corps brut de la requête, calculé avec le secret de webhook obtenu lors de la configuration de votre point de terminaison dans /admin/webhook. Ce secret est une chaîne de 64 caractères affichée une seule fois, à la création — copiez-le immédiatement, car il est masqué ensuite.

En plus de la signature, deux autres en-têtes comptent :

  • X-TextMeFlow-Event-Id — un UUID par message. Les nouvelles tentatives réutilisent le même identifiant : c'est donc votre clé d'idempotence.
  • X-TextMeFlow-Delivery — un UUID par tentative de livraison, utile pour retrouver une nouvelle tentative précise dans vos journaux lors d'un débogage.

Erreur n° 1 : vérifier sur le corps déjà analysé

Le bogue le plus courant consiste à calculer le HMAC sur json_encode($parsedBody) plutôt que sur les octets bruts réellement envoyés par TextMeFlow. Les encodeurs JSON ne garantissent pas une sortie identique à l'octet près : l'ordre des clés, les espaces et le format des nombres flottants peuvent différer entre ce qui a été signé et ce que vous resérialisez. La solution est toujours la même : lisez le corps brut avant qu'un middleware d'analyse JSON n'y touche, et hachez-le.

Dans Express, cela signifie monter express.raw({ type: 'application/json' }) spécifiquement sur votre route de webhook — si express.json() a déjà consommé le corps en amont, les octets bruts ont disparu et vous vérifierez contre undefined. Dans Flask, utilisez request.get_data(), pas request.json. En PHP, file_get_contents('php://input') vous donne le flux intact.

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

Erreur n° 2 : comparer les signatures avec ==

Ne comparez jamais la signature calculée et la signature reçue avec un simple opérateur d'égalité de chaînes. Une vérification naïve avec == ou .equals() divulgue des informations de temps — le nombre d'octets de tête identiques avant l'interruption de la comparaison — ce qui suffit (en théorie) à un attaquant patient pour reconstituer une signature valide octet par octet. Utilisez plutôt une comparaison en temps constant : hash_equals() en PHP, hmac.compare_digest() en Python, crypto.timingSafeEqual() en Node (après avoir vérifié que les longueurs correspondent, car timingSafeEqual lève une exception pour des tampons de longueurs différentes au lieu de renvoyer false).

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

Gérer les nouvelles tentatives sans double traitement

Une livraison est considérée comme réussie dès qu'une réponse 2xx est renvoyée en moins de 10 secondes. Tout le reste déclenche une nouvelle tentative, jusqu'à 5 fois avec des délais de 1m, 5m, 30m, 2h, 6h — cela concerne les réponses 408, 429, 5xx et les expirations de délai réseau. Après 6 tentatives au total (l'originale plus 5 nouvelles tentatives), la livraison est marquée comme échouée, et vous pouvez voir le statut de chaque tentative dans /admin/webhook. Toute autre réponse 4xx est considérée comme un échec définitif, sans nouvelle tentative — un 401 signifie presque toujours que le secret que vous avez enregistré ne correspond plus à celui configuré : vérifiez-le d'abord avant de supposer une attaque.

Comme les nouvelles tentatives sont un comportement attendu et non un cas limite, votre point de terminaison doit être idempotent : enregistrez X-TextMeFlow-Event-Id et ignorez le traitement si vous avez déjà géré cet identifiant. Une contrainte d'unicité sur cette colonne, dans la table où vous consignez les messages entrants, suffit — laissez la base de données rejeter l'insertion en double plutôt que de construire une logique de déduplication maison.

Autre conséquence de la fenêtre de 10 secondes : effectuez le travail proprement dit (mise à jour d'un CRM, déclenchement d'un flux de réservation, appel d'une API aval lente) après avoir répondu 200, et non avant. Accusez réception d'abord, traitez ensuite de manière asynchrone — un gestionnaire lent qui bloque au-delà de 10 secondes ressemble exactement à un délai dépassé et est relancé inutilement.

Migrer depuis TextMeBot

Si vous quittez TextMeBot, la structure de la charge utile est identique (type, from, from_name, to, file, message) : aucun changement dans votre code d'analyse. La seule chose à ajouter est la vérification de signature elle-même — TextMeBot ne signe pas ses webhooks ; si votre ancienne intégration ne vérifiait rien, c'est le moment de combler cette lacune avant la mise en production. La référence complète des champs et la liste des en-têtes se trouvent dans la documentation des webhooks.

Envie d'essayer en direct ? Configurez votre point de terminaison dans /admin/webhook après l'inscription — le plan gratuit inclut 50 messages par mois, pour toujours, de quoi mettre en place et tester un flux de webhook complet. Commencez gratuitement.

Envie d'envoyer des messages WhatsApp via API ?

Gratuit pour toujours jusqu'à 50 messages/mois. Scannez un QR et envoyez votre premier message en 5 minutes.

Gratuit pour toujours