> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Crochets web sortants
> Abonnez-vous aux événements messages, conversations, opt-out et modèles. Vérifiez les signatures HMAC, gérez les tentatives et évitez les doublons.
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**.
Dans l'application Flowella, allez dans **Réglages → Webhooks**.
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.
Flowella génère un secret de signature unique pour le webhook. Copiez-le - vous l'utiliserez pour vérifier les demandes entrantes.
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 :
```http theme={null}
POST https://your-endpoint.example.com/flowella
Content-Type: application/json
User-Agent: Flowella-Webhooks/1
X-Flowella-Signature:
```
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 :
```json theme={null}
{
"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 :
```js theme={null}
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);
}
```
```python theme={null}
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](https://flowella.io/support) - nous ajoutons des événements au fur et à mesure que nos clients nous les demandent.
## En rapport
Configurez les points de terminaison, les secrets de signature et les tentatives dans l'application.
Auth, erreurs, pagination, et limites de taux pour l'API REST.
Créer et faire pivoter les jetons porteurs dont votre point de terminaison peut avoir besoin.
Les mêmes événements sont diffusés dans le flux in-app et dans les courriels.