Webhooks

Un webhook envoie automatiquement le transcript complet d'une session à l'adresse de votre choix dès qu'elle se termine, par exemple à la fin d'un appel avec votre callbot. Vous l'utilisez pour alimenter votre CRM, archiver les échanges dans votre outil de ticketing ou déclencher un traitement après chaque appel. Chaque envoi est signé (HMAC-SHA256), pour que votre serveur puisse vérifier qu'il vient bien de Flowtative.

Comment ça marcheCopier le lien

1. Vous créez un webhook dans Paramètres > Webhooks : un libellé et une URL de destination.
2. Vous le rattachez à un ou plusieurs agents depuis l'éditeur d'agent, section Webhooks.
3. À la fin de chaque session d'un agent, Flowtative envoie le transcript en POST à tous les webhooks qui sont rattachés à cet agent, actifs et abonnés à l'événement BOT_SESSION_ENDED.

Avant de commencerCopier le lien

• Préparez une URL publique en https:// capable de recevoir une requête POST. Les URL en http:// sont refusées (« HTTPS obligatoire. »).
• Prévoyez un endroit sûr côté serveur pour stocker le secret de signature. Il ne s'affiche qu'une seule fois.

Créer un webhookCopier le lien

1. Ouvrez Paramètres, puis l'onglet Webhooks.
2. Cliquez sur Nouveau webhook.
3. Renseignez les champs ci-dessous.
4. Cliquez sur Créer et obtenir le secret.
5. Dans la fenêtre Secret de signature, cliquez sur Copier, stockez le secret sur votre serveur, puis cliquez sur J'ai copié le secret.

Le webhook est créé actif et abonné à l'événement BOT_SESSION_ENDED (fin de session bot).

Si la création réussit mais que le secret n'a pas pu être généré, un message indique « Webhook créé, mais sans secret de signature : … ». Le webhook existe : générez son secret avec l'icône de clé.

Rattacher un webhook à un agentCopier le lien

1. Ouvrez l'agent dans l'éditeur, puis la section Webhooks (groupe Intelligence).
2. Cochez les webhooks qui doivent recevoir les transcripts de cet agent.
3. Enregistrez l'agent.

Vous pouvez aussi cliquer sur Créer un webhook pour cet agent : le formulaire crée le webhook, l'abonne à BOT_SESSION_ENDED et le coche d'office (Créer et rattacher). Le secret s'affiche de la même façon.

La liste signale les situations à corriger :

Le lien Gérer les webhooks (URL, secret, journal des livraisons) vous ramène aux paramètres.

Gérer vos webhooksCopier le lien

Chaque webhook apparaît sous forme de carte avec son libellé, son URL et ses événements. Au-delà de 10 webhooks, une barre Filtrer par libellé ou URL… et une pagination apparaissent.

Journal des livraisons en échecCopier le lien

Seuls les échecs sont journalisés. Quand tout fonctionne, le panneau indique « Aucune erreur de livraison — seuls les échecs sont journalisés. ». Chaque ligne affiche la date et la description de l'erreur. Cliquez dessus pour voir le contenu exact qui devait être envoyé. Le bouton Rafraîchir recharge le journal.

Renouveler le secretCopier le lien

1. Cliquez sur l'icône de clé (Générer un nouveau secret HMAC).
2. Le message « Invalide l'ancienne signature — confirmer » apparaît. Cliquez sur confirmer.
3. Copiez le nouveau secret et mettez-le à jour sur votre serveur.

Vérifier la signatureCopier le lien

Chaque envoi porte deux en-têtes HTTP :

La signature se calcule ainsi : v1 = HMAC-SHA256(secret, timestamp + "." + corps brut). Pour la vérifier :

1. Lisez les deux en-têtes. Rejetez la requête s'il en manque un.
2. Rejetez la requête si l'horodatage a plus de 5 minutes environ. Vous vous protégez ainsi contre le rejeu d'un ancien envoi.
3. Recalculez la signature sur le corps brut, avant tout décodage JSON, et comparez-la à la valeur v1 avec une comparaison à temps constant.

La fenêtre du secret propose ces extraits prêts à coller en Node.js et en Python :

import crypto from "node:crypto";

function verify(rawBody, headers, secret, toleranceSeconds = 300) {
  const timestamp = headers["x-via-timestamp"];
  const v1 = headers["x-via-signature"]?.split(",")
    .find((p) => p.startsWith("v1="))?.slice(3);
  if (!timestamp || !v1) return false;
  const age = Math.floor(Date.now() / 1000) - Number(timestamp);
  if (age < 0 || age > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(timestamp + ".").update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
}

Exemple : alimenter le CRM après chaque appelCopier le lien

Votre service client utilise un callbot de prise de rendez-vous et vous voulez retrouver chaque conversation dans la fiche client du CRM.

1. Votre équipe technique expose https://crm.exemple.com/hooks/flowtative, qui vérifie la signature puis rattache le transcript au contact par son numéro.
2. Vous créez le webhook CRM avec cette URL et transmettez le secret à l'équipe technique.
3. Dans l'éditeur du callbot, section Webhooks, vous cochez CRM et enregistrez.
4. Vous passez un appel de test, puis vous vérifiez le journal Livraisons en échec : s'il est vide, l'envoi a réussi.

Bonnes pratiquesCopier le lien

• Répondez vite côté serveur (un simple accusé de réception), puis traitez le transcript en arrière-plan.
• Utilisez un webhook par système destinataire plutôt qu'une URL qui redistribue : vous gardez un journal d'échecs lisible pour chacun.
• Désactivez un webhook plutôt que de le supprimer pendant une maintenance du serveur destinataire : les rattachements aux agents sont conservés.

Pour aller plus loinCopier le lien