Webhooks entrants

À quoi ça sert

Un webhook entrant est une adresse publique que Deltia expose pour qu'un outil externe (une boutique en ligne, un service de paiement, un outil maison) vous prévienne qu'il s'est passé quelque chose. Chaque appel authentifié que reçoit cette adresse peut déclencher une règle d'automatisation, qui lit le contenu de l'appel (corps, en-têtes, paramètres d'adresse) comme des variables.

La gestion des webhooks est réservée aux administrateurs du module Connecteurs. Elle se trouve dans l'onglet « Webhooks » de l'administration des connecteurs.

Concepts clés

• Webhook — une adresse publique créée par un administrateur, avec un nom, un mode d'authentification et, au besoin, une liste d'adresses autorisées.
• URL du webhook — elle contient un secret. Quiconque la connaît peut l'appeler : ne la partagez pas, et changez-la si elle a fuité.
• Secret — le jeton, le mot de passe ou la clé de signature qui prouve que l'appel vient bien de votre outil. Deltia l'affiche une seule fois.
• Dernier appel reçu — le contenu du dernier appel accepté. Les automatisations s'en servent pour proposer les variables disponibles.

Comment faire

Exposer un webhook

1. Cliquez sur votre avatar, puis, sous « Administration », sur « Intégrations », puis ouvrez l'administration des connecteurs.
2. Ouvrez l'onglet « Webhooks » et cliquez sur « Exposer un webhook ».
3. Saisissez le « Nom », puis choisissez l'« Authentification » (voir la référence ci-dessous).
4. Au besoin, renseignez les « Adresses autorisées (facultatif) ».
5. Cliquez sur « Exposer ».

Le panneau affiche l'« URL du webhook » et, selon le mode, le « Secret ». Copiez-les maintenant et renseignez-les chez l'émetteur : le secret ne sera plus affiché, mais l'URL reste consultable en rouvrant le webhook.

Faire déclencher une automatisation

1. Appelez l'URL une fois depuis votre outil : le contenu de cet appel est conservé dans « Dernier appel reçu ».
2. Créez ou modifiez une règle d'automatisation et choisissez le webhook comme déclencheur (« Choisir une boîte mail ou un webhook »).
3. Les champs du dernier appel sont proposés comme variables.

Voir Déclencheurs.

Modifier un webhook

1. Dans l'onglet « Webhooks », cliquez sur le bouton de modification de la ligne.
2. Changez le nom, le mode ou les adresses autorisées, puis enregistrez.

Les identifiants déjà émis sont conservés quand vous modifiez ou désactivez un webhook.

Suspendre un webhook

Dans la colonne « Actif », basculez l'interrupteur. Un webhook inactif répond comme une adresse inconnue.

Générer un nouveau secret ou changer l'URL

1. Ouvrez le webhook.
2. Cliquez sur « Générer un nouveau secret » ou sur « Changer l'URL », puis confirmez.

L'ancien secret ou l'ancienne URL cesse de fonctionner immédiatement : mettez l'émetteur à jour aussitôt. Pour un webhook dont l'émetteur fournit lui-même le secret de signature (Shopify, Stripe), « Générer un nouveau secret » n'est pas proposé.

Supprimer un webhook

1. Cliquez sur le bouton de suppression de la ligne et confirmez.

L'adresse cesse de répondre pour de bon : les outils qui l'appellent reçoivent une erreur 404. Un webhook utilisé comme déclencheur par une règle ne peut pas être supprimé tant que la règle existe.

Référence

Modes d'authentification

Sans authentification, quiconque connaît l'URL peut déclencher vos automatisations : Deltia affiche un avertissement.

Signature HMAC

Le champ « Émetteur de la signature » propose « GitHub », « Shopify », « Stripe », « Standard Webhooks » et « Personnalisé ». Pour « Personnalisé », vous précisez le nom de l'en-tête, l'« Algorithme » (« SHA-256 » ou « SHA-1 »), l'« Encodage » (« Hexadécimal » ou « Base64 ») et le « Préfixe de la signature », par exemple « sha256= ». Avec « Shopify » et « Stripe », c'est l'émetteur qui fournit le secret : vous le collez dans « Secret de signature ». Pour les autres, laissez le champ vide et Deltia en génère un.

Adresses autorisées

Une adresse IP ou une plage CIDR par ligne, par exemple « 203.0.113.0/24 ». Le champ vide accepte toutes les adresses. La liste s'ajoute à l'authentification choisie, elle ne la remplace pas.

Réponses de l'adresse

Ce que reçoit l'automatisation

La règle lit l'identifiant du webhook, l'identifiant et la date de l'appel, le corps, les en-têtes et les paramètres d'adresse. Le corps s'explore avec des points ; une clé qui contient un tiret ou un espace ne peut pas être nommée. Les en-têtes d'authentification et de signature ne sont jamais conservés. L'appel reçu est conservé en entier, corps compris, dans l'historique des exécutions. Un même appel renvoyé par l'émetteur ne lance la règle qu'une fois.

Questions fréquentes

Puis-je revoir le secret d'un webhook ? Non. Générez-en un nouveau : l'ancien cesse de fonctionner.

Un webhook peut-il lancer une règle sans règle associée ? Non. Il enregistre le dernier appel, mais seules les règles qui le choisissent comme déclencheur s'exécutent.