Suivre
Webhooks
Être prévenu en temps réel de la livraison de vos messages, des codes vérifiés et des messages reçus.
Un webhook est une adresse de votre application à laquelle Flare envoie une requête POST à chaque événement : un message livré, lu ou en échec, un code vérifié, un message reçu sur votre numéro. Plus besoin d'interroger l'API en boucle.
Ajouter une adresse
Dans l'espace client, ouvrez Configurer › Webhooks et cliquez sur Nouveau webhook :
- Adresse de réception : une URL publique de votre application, de préférence en HTTPS ;
- Événements : ceux qui vous intéressent, ou aucun pour tout recevoir.
Le bouton Tester envoie un événement webhook.test ; le résultat apparaît dans Livraisons.
Les événements
| Événement | Quand |
|---|---|
message.sent |
Un message est parti du numéro expéditeur. |
message.delivered |
Il est arrivé sur le téléphone du destinataire. |
message.read |
Le destinataire l'a lu. |
message.failed |
Il a été abandonné. |
otp.verified |
Un code OTP a été vérifié avec succès. |
message.received |
Votre numéro dédié a reçu un message. |
sender.status |
L'état de votre numéro dédié a changé (délié, restreint, reconnecté…). |
Format d'une requête
Chaque requête porte un corps JSON de la forme :
{
"event": "message.delivered",
"created_at": "2026-11-17T09:43:05+00:00",
"data": {
"id": "01JD40A1B3D5F7H9K1M3P5R7T9",
"kind": "otp",
"to": "+237699001122",
"status": "delivered",
"otp_id": "01JD3ZQ7V9K2M4N6P8R0T2V4X6",
"reference": "user_4512",
"event": null,
"error": null,
"sent_at": "2026-11-17T09:43:03+00:00",
"delivered_at": "2026-11-17T09:43:05+00:00",
"read_at": null
}
}
Et ces en-têtes :
| En-tête | Contenu |
|---|---|
X-Flare-Event |
Le nom de l'événement. |
X-Flare-Delivery |
L'identifiant de cette livraison, identique à chaque nouvel essai. |
X-Flare-Signature |
sha256= suivi de la signature HMAC du corps. |
User-Agent |
Flare-Webhooks/1.0 |
message.*
Pour message.sent, message.delivered, message.read et message.failed, data contient le message, comme ci-dessus. En cas d'échec, error vaut par exemple :
{ "code": "no_sender_available", "message": "Aucun numéro expéditeur n’est disponible pour le moment." }
otp.verified
{
"event": "otp.verified",
"created_at": "2026-11-17T09:44:12+00:00",
"data": {
"id": "01JD3ZQ7V9K2M4N6P8R0T2V4X6",
"to": "+237699001122",
"reference": "user_4512",
"verified_at": "2026-11-17T09:44:12+00:00"
}
}
message.received
Seuls les numéros dédiés transmettent les messages reçus.
{
"event": "message.received",
"created_at": "2026-11-17T10:02:40+00:00",
"data": {
"sender_id": 12,
"id": "false_237699001122@c.us_3EB0C767D26B8A3F1A2B",
"from": "237699001122@c.us",
"chat_id": "237699001122@c.us",
"is_group": false,
"type": "chat",
"text": "Bonjour, ma commande est-elle partie ?",
"contact_name": "Awa",
"timestamp": 1794996160
}
}
sender_id indique lequel de vos numéros a reçu le message, type la nature du message (texte, image, document…) telle que WhatsApp la rapporte, et timestamp l'heure de réception en secondes.
sender.status
{
"event": "sender.status",
"created_at": "2026-11-17T11:15:00+00:00",
"data": {
"sender_id": 12,
"label": "Service client",
"phone": "+237677001122",
"status": "disconnected",
"restricted": false
}
}
Vérifier la signature
Chaque webhook a un secret de signature, visible dans l'espace client (Voir le secret de signature). Calculez le HMAC-SHA256 du corps brut de la requête avec ce secret, et comparez-le à l'en-tête X-Flare-Signature. Refusez toute requête dont la signature ne correspond pas.
// Laravel : routes/web.php ou un contrôleur (excluez cette route de la protection CSRF).
Route::post('/webhooks/flare', function (Request $request) {
$expected = 'sha256='.hash_hmac('sha256', $request->getContent(), env('FLARE_WEBHOOK_SECRET'));
abort_unless(hash_equals($expected, (string) $request->header('X-Flare-Signature')), 401);
$event = $request->input('event');
$data = $request->input('data');
// … traitez l'événement, idéalement dans une file d'attente.
return response()->noContent();
});
// Express : récupérez le corps brut, pas le JSON déjà analysé.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post('/webhooks/flare', express.raw({ type: 'application/json' }), (req, res) => {
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.FLARE_WEBHOOK_SECRET)
.update(req.body)
.digest('hex');
const received = req.get('X-Flare-Signature') ?? '';
const valid = expected.length === received.length
&& crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
if (!valid) return res.sendStatus(401);
const { event, data } = JSON.parse(req.body);
// … traitez l'événement.
res.sendStatus(204);
});
# Flask
import hashlib, hmac, os
from flask import Flask, abort, request
app = Flask(__name__)
@app.post("/webhooks/flare")
def flare_webhook():
expected = "sha256=" + hmac.new(
os.environ["FLARE_WEBHOOK_SECRET"].encode(),
request.get_data(),
hashlib.sha256,
).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Flare-Signature", "")):
abort(401)
payload = request.get_json()
# … traitez payload["event"] et payload["data"].
return "", 204
Attention : calculez la signature sur le corps tel qu'il a été reçu. Un JSON décodé puis réencodé peut différer d'un octet, et la signature ne correspondrait plus.
Répondre, et les nouveaux essais
- Répondez par un code 2xx dans les 8 secondes. Faites le traitement long plus tard, dans une file d'attente.
- En cas d'erreur, de délai dépassé ou de code autre que 2xx, Flare réessaie jusqu'à 5 fois, après 10 secondes, 1 minute, 5 minutes puis 30 minutes.
- Les redirections ne sont pas suivies : donnez l'adresse finale.
- Un même événement peut arriver plus d'une fois. Servez-vous de l'en-tête
X-Flare-Deliverypour ne pas le traiter deux fois. - Les événements peuvent arriver dans le désordre (un
message.readavant lemessage.delivered). Fiez-vous au statut le plus avancé.
L'historique des livraisons, avec le code de réponse de votre application, est visible dans Livraisons, pendant 30 jours.
Sécurité du secret
Le bouton Régénérer le secret crée un nouveau secret et désactive immédiatement l'ancien : mettez votre application à jour juste après. Les adresses privées (localhost, réseau interne) sont refusées.