Fonctionnalités

Webhooks

Envoyez une requête HTTP vers une autre application lorsqu'un événement se produit sur un document.

Webhooks

Un Webhook envoie une requête HTTP vers une autre application quand un événement se produit sur un document. Exemple : prévenir un outil externe à chaque validation d'une commande client.

Prérequis

  • Le rôle Gestionnaire système.
  • L'URL de l'application qui reçoit les données.

Pour accéder à la liste des Webhook, cliquez sur l'icône de recherche de la barre latérale gauche (ou appuyez sur Ctrl+K), puis saisissez Webhook. Le webhook se trouve dans le module Intégrations.

1. Comment configurer un Webhook ?

  1. Dans la liste, cliquez sur Créer un·e Webhook, puis saisissez le Nom du webhook. Ce champ est obligatoire.
  2. Dans la section Événements Doc, sélectionnez le Type de document pour lequel le Webhook doit être déclenché (par exemple Devis client).
  3. Sélectionnez l'Événement Doc qui déclenchera le Webhook.
Événement DocDéclenché quand
after_insertle document est créé
on_updatele document est enregistré
on_submitle document est validé
on_cancelle document est annulé
on_trashle document est supprimé
on_update_after_submitun document validé est modifié
on_changeune valeur du document change, y compris par un traitement automatique
workflow_transitionle document change d'état dans un flux de travail

Les événements on_submit, on_cancel et on_update_after_submit demandent un type de document validable.

Les webhooks ne partent pas pendant un import de données, une migration ou l'installation d'une application.

1.1 Déclencheur du webhook

Dans Condition, saisissez une expression Python sur doc. Le webhook part seulement si elle est vraie. Exemple : doc.grand_total > 1000. Dokos refuse d'enregistrer une condition invalide.

1.2 Requête Webhook

  1. Dans URL de Demande, saisissez une URL valide qui recevra les données du Webhook. Cochez Est une URL dynamique ? pour traiter l'URL comme un modèle Jinja, par exemple https://exemple.fr/api/commandes/{{ doc.name }}.
  2. Sélectionnez la Méthode de la demande : POST (par défaut), PUT ou DELETE.
  3. Sélectionnez la Structure de la requête : « Form URL-Encoded » ou « JSON ».
  4. En option, modifiez le Délai d'expiration de la requête (5 secondes par défaut) et la File d'attente de tâche de fond.

1.3 Sécurité des webhooks

Pour éventuellement ajouter de la sécurité à vos demandes de webhook et vous assurer que le webhook est envoyé depuis Dokos, cochez Activer la sécurité, puis saisissez un Secret du Webhook. Ce champ est masqué : cliquez sur l'icône en forme d'œil pour afficher sa valeur. Ne partagez pas le secret publiquement.

Avec la sécurité active, chaque requête porte l'en-tête X-Frappe-Webhook-Signature. Sa valeur est la signature HMAC-SHA256 du corps de la requête, calculée avec le secret et encodée en base64. L'application qui reçoit la requête refait ce calcul pour vérifier l'origine.

1.4 En-Têtes Webhook

Vous pouvez éventuellement ajouter des en-têtes HTTP à la requête (par exemple pour envoyer une clé API). Cliquez sur Ajouter une ligne pour ajouter un en-tête. Renseignez la clé et la valeur, par exemple Authorization et token abc123 (exemple fictif).

Vous pouvez également désactiver un webhook en décochant la case Activé. Seuls les webhooks activés sont déclenchés.

1.5 Données du Webhook

Si la structure de votre demande est basée sur des formulaires, vous pouvez sélectionner des champs du document dans le tableau. Les colonnes Nom du champ et Clé sont obligatoires. Si vous choisissez la structure Form URL-Encoded, Dokos ajoute automatiquement l'en-tête Content-Type: application/x-www-form-urlencoded. Si la structure de votre demande est basée sur JSON, saisissez le Corps de requête JSON avec des balises Jinja. Mettez les valeurs texte entre guillemets doubles. Exemple fictif :

{
  "commande": "{{ doc.name }}",
  "client": "{{ doc.customer }}",
  "montant": {{ doc.grand_total }}
}

Le bouton Aperçu montre, pour un document choisi, si la condition est remplie et le corps de la requête.

1.6 Journal des demandes de webhook

Dokos envoie la requête en tâche de fond, après l'enregistrement du document. En cas d'échec, il fait jusqu'à 3 essais à quelques secondes d'intervalle.

Chaque essai crée un Journal de la demande de Webhook : URL, en-têtes, données, réponse et erreur éventuelle. Ouvrez-le depuis la recherche pour vérifier une livraison.