Aller au contenu

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 :

JSON
{
  "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 :

JSON
{ "code": "no_sender_available", "message": "Aucun numéro expéditeur n’est disponible pour le moment." }

otp.verified

JSON
{
  "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.

JSON
{
  "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

JSON
{
  "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();
});

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-Delivery pour ne pas le traiter deux fois.
  • Les événements peuvent arriver dans le désordre (un message.read avant le message.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.