Crochets web sortants

Les webhooks sortants permettent à vos systèmes de réagir aux événements de Flowella en temps réel, sans avoir à interroger l’API. Vous configurez une URL et une liste de types d’événements, et Flowella POSTE un fichier JSON signé à cette URL chaque fois qu’un de ces événements se produit.

Configuration d’un webhook

Vous devez avoir le rôle Owner ou Admin.

Ouvrez Paramètres → Webhooks

Dans l’application Flowella, allez dans Réglages → Webhooks.

Ajouter un webhook

Cliquez sur Add webhook, collez l’URL HTTPS publique de votre point d’accès, et choisissez les types d’événements que vous souhaitez recevoir.

Enregistrer le secret de signature

Flowella génère un secret de signature unique pour le webhook. Copiez-le - vous l’utiliserez pour vérifier les demandes entrantes.

Envoyer un test

Cliquez sur Envoyer un test pour envoyer immédiatement une charge utile webhook.test. Vérifiez que votre terminal l’a reçu et qu’il a répondu par un 2xx.

Types d’événements

Vous pouvez vous abonner à n’importe lequel de ces événements :

Événement	Lorsqu’il se déclenche
`message.received`	Un message entrant WhatsApp est arrivé de la part d’un contact.
`message.sent`	Flowella a accepté votre message sortant et l’a soumis à Meta.
`message.delivered`	Meta a confirmé que le message a été délivré à l’appareil du destinataire.
`message.read`	Le destinataire a ouvert le message.
`message.failed`	Meta a renvoyé un échec pour le message.
`conversation.opened`	Une conversation est passée à l’état ouvert
`conversation.closed`	Une conversation a été fermée
`optout.created`	Un contact s’est retiré d’un canal spécifique
`template.status_updated`	Meta a changé le statut d’un modèle (approuvé, rejeté, en pause, désactivé)

webhook.test est envoyé uniquement lorsque vous cliquez sur Envoyer un test - vous ne vous y abonnez pas explicitement.

Format de la demande

Flowella POST un corps JSON à votre URL avec ces en-têtes :

POST https://your-endpoint.example.com/flowella
Content-Type: application/json
User-Agent: Flowella-Webhooks/1
X-Flowella-Signature: <hex digest>

Les données utiles sont plafonnées à 256 KB. Les objets plus volumineux sont résumés - utilisez l’API pour récupérer l’enregistrement complet par ID si vous en avez besoin. La forme du corps varie en fonction de l’événement mais comprend toujours :

{
  "event": "message.delivered",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "organizationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": { "...event-specific fields..." }
}

Vérification des signatures

Chaque requête inclut un en-tête X-Flowella-Signature. La valeur est le HMAC-SHA256 hex digest du corps de la requête UTF-8 brut avec la clé du secret de signature de votre webhook. Vérifiez-le avant de le traiter :

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signatureHeader, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Signez toujours sur les octets bruts du corps avant toute analyse JSON ou tout logiciel intermédiaire reformatant la charge utile. Si votre framework resérialise JSON, la signature ne correspondra pas.

Réponses, tentatives et délais d’attente

Timeout : Flowella attend jusqu’à 10 secondes que votre terminal réponde.
Succès** : toute réponse de 2xx est considérée comme une livraison réussie.
Retries : les livraisons échouées sont retentées jusqu’à 3 tentatives avec backoff.
Désactivation automatique** : si un webhook accumule 10 échecs consécutifs, Flowella le désactive. Vous devrez le réactiver depuis Paramètres → Webhooks après avoir corrigé votre point d’accès.

Votre point d’accès doit revenir aussi vite que possible - reportez tout traitement lourd sur une file d’attente en arrière-plan de votre côté.

Idempotence

Les webhooks peuvent être relancés, de sorte que le même événement logique peut arriver plus d’une fois. Pour traiter en toute sécurité :

Utilisez le data.id de l’événement (ou une clé dérivée comme event + data.messageId) comme clé d’idempotence.
Conservez un cache de courte durée pour les clés traitées (quelques heures suffisent pour les nouvelles tentatives).
Traitez les doublons comme des “no-ops”.

Lister et gérer les livraisons

Réglages → Webhooks affiche les tentatives de livraison récentes par webhook, y compris :

Horodatage
Type d’événement
État de la réponse
Un corps de réponse tronqué (jusqu’à ~1 KB) pour le débogage

Si un webhook est désactivé en raison d’échecs répétés, la même page vous permet de le réactiver.

Développement local

La manière la plus simple de développer localement avec des webhooks est de transférer un tunnel public (par exemple, ngrok ou Cloudflare Tunnel) vers votre serveur de développement et de faire pointer l’URL du webhook vers l’hôte du tunnel. Utilisez Send test pour envoyer des payloads à la demande sans attendre l’activité réelle de WhatsApp.

Vous souhaitez réagir à des événements qui ne figurent pas sur la liste ? Dites-le nous à support - nous ajoutons des événements au fur et à mesure que nos clients nous les demandent.

En rapport

Paramètres → Webhooks

Configurez les points de terminaison, les secrets de signature et les tentatives dans l’application.

Introduction à l'API

Auth, erreurs, pagination, et limites de taux pour l’API REST.

Clés API

Créer et faire pivoter les jetons porteurs dont votre point de terminaison peut avoir besoin.

Événements de notification

Les mêmes événements sont diffusés dans le flux in-app et dans les courriels.

Premiers pas

Journal des modifications

Essentiels

Utiliser l'application

Paramètres

Configuration Meta et WhatsApp

Intégration HubSpot

Flows et campagnes

Compte et connexion

Sécurité et confidentialité

Référence API

Dépannage

Crochets web sortants

Configuration d’un webhook

Types d’événements

Format de la demande

Vérification des signatures

Réponses, tentatives et délais d’attente

Idempotence

Lister et gérer les livraisons

Développement local

En rapport

Paramètres → Webhooks

Introduction à l'API

Clés API

Événements de notification

​Configuration d’un webhook

​Types d’événements

​Format de la demande

​Vérification des signatures

​Réponses, tentatives et délais d’attente

​Idempotence

​Lister et gérer les livraisons

​Développement local

​En rapport

Paramètres → Webhooks

Introduction à l'API

Clés API

Événements de notification

Configuration d’un webhook

Types d’événements

Format de la demande

Vérification des signatures

Réponses, tentatives et délais d’attente

Idempotence

Lister et gérer les livraisons

Développement local

En rapport