Webhooks sortants

Pour :Administrateur

Vue de la page « webhooks »

Un webhook sortant est une notification HTTP que Unisoft envoie à une URL de votre choix dès qu'un événement métier se produit dans votre organisation (un paiement réussi, un formulaire soumis, un nouveau contact créé…). C'est le mécanisme idéal pour réagir en temps réel sans avoir à interroger l'API en boucle.

Ouvrir l'onglet Webhooks

1. 1

   Aller sur la page Développeurs

   Tapez l'URL /app/developpeurs/tabs dans la barre d'adresse.

2. 2

   Cliquer sur l'onglet « Webhooks sortants »

   L'onglet est à droite de l'onglet Clés API.

Comprendre le tableau

Le tableau central liste les webhooks configurés pour votre organisation. Pour chacun, vous voyez :

Colonne	Contenu
Nom	Le libellé que vous avez choisi (ex. Make - sync Mailchimp)
URL	L'URL cible, partiellement masquée pour ne pas exposer le chemin secret
Événements	Les événements écoutés (tags)
Dernier succès	Date relative du dernier envoi réussi, ou jamais
Statut	Actif (vert), Inactif (gris), En quarantaine (orange), ou nombre d'échecs (jaune)
Actions	Boutons Test, Modifier, Régénérer le secret, Supprimer

Créer un nouveau webhook

1. 1

   Cliquer sur « Nouveau webhook »

   Le bouton se trouve en haut à droite de l'onglet. Une modale s'ouvre.

2. 2

   Donner un nom évocateur

   Saisissez un nom descriptif comme Make - sync Mailchimp ou Slack alertes dons. Vous vous y retrouverez plus tard quand vous aurez plusieurs webhooks.

3. 3

   Renseigner l'URL cible

   L'URL fournie par votre outil (catch hook Make, webhook Zapier, endpoint de votre script…). HTTPS obligatoire — les URL en http:// ou pointant vers des adresses locales ne sont pas acceptées.

4. 4

   Choisir les événements à recevoir

   Sélectionnez un ou plusieurs événements dans la liste (voir la table ci-dessous). Vous pouvez en sélectionner plusieurs si la même URL doit recevoir différents types de notifications.

5. 5

   Cliquer sur « Créer le webhook »

   Une nouvelle modale s'affiche immédiatement avec le secret de signature.

6. 6

   Copier le secret sans attendre

   Cliquez sur « Copier le secret ». Vous ne reverrez jamais ce secret une fois la modale fermée — collez-le immédiatement dans votre outil ou votre gestionnaire de mots de passe.

7. 7

   Confirmer

   Cliquez sur « J'ai bien copié le secret » pour fermer la modale.

⛔

Affiché une seule fois

Le secret n'est affiché qu'une seule fois, juste après la création. Si vous le perdez, il faudra utiliser le bouton Régénérer le secret (l'ancien sera invalidé).

Les événements disponibles

Chaque webhook écoute un ou plusieurs événements. Voici les principaux disponibles :

Événement	Déclenché quand…
paiement.success	Un paiement est encaissé avec succès
paiement.refunded	Un paiement est remboursé
form.submitted	Un formulaire est soumis par un visiteur
contact.created	Un nouveau contact est créé dans le module Contacts
*	Tous les événements (à réserver au debug ou aux outils centralisés type log aggregator)

ℹ

Liste évolutive

D'autres événements peuvent être ajoutés au fil des versions. Le sélecteur de la modale affiche toujours la liste à jour disponible pour votre organisation.

La signature HMAC : vérifier que la notification vient bien d'Unisoft

Quand Unisoft envoie une notification à votre URL, il joint une signature cryptographique calculée avec le secret partagé. Votre outil doit vérifier cette signature pour s'assurer que la notification est légitime (et non un appel malveillant qui imite Unisoft).

Principe

1. Unisoft calcule un HMAC SHA-256 du corps de la requête, en utilisant votre secret comme clé.
2. La signature est jointe à la requête HTTP (généralement dans un entête X-Unisoft-Signature ou équivalent).
3. Votre outil recalcule de son côté la signature à partir du corps reçu et de son secret.
4. Si les deux signatures coïncident, la notification est authentique.

Côté Make / Zapier

Make et Zapier proposent souvent une validation de signature native dans leur module Webhook. Renseignez simplement le secret dans le champ prévu : la plateforme vérifie automatiquement.

Côté script maison

Si vous écrivez votre propre endpoint, votre code doit :

1. Lire le corps brut de la requête HTTP.
2. Lire la signature dans l'entête.
3. Calculer le HMAC SHA-256 du corps avec votre secret.
4. Comparer les deux. Rejeter (avec un code 401) si la signature ne correspond pas.

Le format exact de l'entête et l'éventuel timestamp pour la protection contre le replay sont décrits dans la documentation Swagger interactive (bouton Documentation API).

Exemple de payload reçu

Quand un nouveau paiement est encaissé, votre URL reçoit une requête HTTP POST avec un corps JSON dont la structure ressemble à :

{
  "type": "paiement.success",
  "createdAt": "2026-05-18T10:32:14.000Z",
  "organisation": "org_abc123",
  "data": {
    "id": "pmt_xyz789",
    "amount": 5000,
    "currency": "EUR",
    "contact": {
      "id": "ctc_def456",
      "firstName": "Sarah",
      "lastName": "Cohen",
      "email": "sarah.cohen@exemple-unisoft.org"
    },
    "reason": "Don à la Caisse principale"
  }
}

Le format exact (champs disponibles, conventions de nommage) est documenté événement par événement dans le Swagger.

Tester un webhook

Le bouton Test envoie un événement factice webhook.test à votre URL pour vérifier la connectivité, sans attendre qu'un véritable événement se produise.

1. 1

   Cliquer sur le bouton Test

   Icône Play (▶) dans la colonne Actions de la ligne du webhook.

2. 2

   Vérifier dans votre outil

   Make / n8n / Zapier doivent recevoir une requête POST avec type: "webhook.test". Si oui, votre intégration est correctement configurée.

3. 3

   En cas d'échec

   Vérifiez : l'URL est-elle bien en HTTPS ? Le serveur cible accepte-t-il les requêtes externes ? Le pare-feu autorise-t-il l'IP d'Unisoft ?

★

À utiliser dès la création

Lancez systématiquement un Test juste après avoir créé un webhook. Cela évite de découvrir des semaines plus tard qu'aucun événement n'arrivait à destination.

Modifier un webhook

1. 1

   Cliquer sur l'icône Modifier

   Icône crayon dans la colonne Actions.

2. 2

   Ajuster les champs

   Vous pouvez modifier le nom, l'URL ou la liste des événements. Le secret reste inchangé.

3. 3

   Enregistrer

   Les modifications sont prises en compte dès le prochain événement.

Régénérer le secret (rotation)

Si vous soupçonnez que votre secret a été compromis (apparition dans un dépôt Git public, ancien collaborateur, etc.), régénérez-le immédiatement.

1. 1

   Cliquer sur l'icône Régénérer

   Icône Refresh (orange) dans la colonne Actions.

2. 2

   Confirmer

   Une demande de confirmation rappelle que l'ancien secret sera invalidé immédiatement.

3. 3

   Copier le nouveau secret

   Une modale affiche le nouveau secret, une seule fois. Copiez-le et remplacez l'ancien dans votre outil destinataire.

⚠

Coordination requise

Pendant le bref intervalle entre la régénération et la mise à jour de votre outil, les webhooks reçus ne pourront pas être validés par celui-ci. Préparez le remplacement à l'avance dans votre outil pour minimiser la coupure.

Le circuit-breaker : protection automatique en cas d'erreurs

Si votre URL cible échoue plusieurs fois de suite (serveur en panne, mauvaise URL, certificat HTTPS expiré…), Unisoft désactive automatiquement le webhook pendant un certain temps. Le statut passe alors à « En quarantaine » (tag orange).

Cette protection évite de noyer votre serveur d'appels qui échouent et de gaspiller des ressources des deux côtés.

Comment sortir de la quarantaine

1. 1

   Identifier la cause de l'échec

   Consultez les logs de votre outil ou de votre serveur. Vérifiez que l'URL répond correctement avec un code HTTP 2xx.

2. 2

   Tester le webhook

   Utilisez le bouton Test pour vérifier que l'URL fonctionne à nouveau.

3. 3

   Modifier le webhook

   Ouvrez le formulaire d'édition et enregistrez (même sans modification) pour réinitialiser le compteur d'erreurs.

Supprimer un webhook

1. 1

   Cliquer sur l'icône Supprimer

   Icône de poubelle rouge dans la colonne Actions.

2. 2

   Confirmer

   Le webhook est définitivement supprimé. Plus aucune notification ne sera envoyée à cette URL.

Cas pratique : synchroniser les nouveaux contacts vers Mailchimp en temps réel

1. 1

   Préparer un scénario Make

   Créez un nouveau scénario Make commençant par le déclencheur Webhook → Custom webhook. Make génère une URL unique du type https://hook.make.com/abc123xyz.... Copiez-la.

2. 2

   Créer le webhook dans Unisoft

   Onglet Webhooks → Nouveau webhook. Nom : Make - sync Mailchimp. URL : celle générée par Make. Événements : contact.created. Créez et copiez le secret affiché.

3. 3

   Tester depuis Unisoft

   Cliquez sur le bouton Test dans Unisoft. Make doit recevoir l'événement et afficher le payload reçu. Si oui, validez le déclencheur.

4. 4

   Ajouter le module Mailchimp dans Make

   Connectez votre compte Mailchimp, puis ajoutez l'action Add/Update Subscriber en mappant les champs reçus du webhook (firstName, lastName, email) vers les champs Mailchimp.

5. 5

   Activer le scénario

   Activez le scénario dans Make. Désormais, chaque nouveau contact dans Unisoft sera ajouté à Mailchimp en quelques secondes.

Pièges à éviter

Piège	Conséquence	Solution
URL en HTTP au lieu de HTTPS	Webhook refusé à la création	Activez HTTPS sur votre endpoint (Make, Zapier et n8n le font nativement)
Ne pas vérifier la signature HMAC	N'importe qui peut imiter Unisoft et appeler votre URL	Activez la validation de signature dans votre outil ou implémentez-la dans votre script
Stocker le secret en clair dans un fichier de configuration	Compromission possible	Utilisez les variables d'environnement de votre outil ou un coffre-fort
Ignorer la mise en quarantaine	Vos événements sont perdus pendant la coupure	Surveillez le statut et réagissez quand un webhook passe en orange
Envoyer une réponse HTTP lente (>30 s)	Unisoft considère l'appel comme un échec et incrémente le compteur d'erreurs	Répondez rapidement (200 OK) et traitez en asynchrone dans votre outil

À retenir

• Un webhook sortant est une notification HTTP envoyée par Unisoft à votre URL dès qu'un événement métier se produit.
• L'URL doit être en HTTPS et le secret de signature est affiché une seule fois.
• La signature HMAC SHA-256 garantit que la notification vient bien d'Unisoft — vérifiez-la côté outil destinataire.
• Le bouton Test envoie un événement factice utile pour valider la configuration.
• Le circuit-breaker désactive temporairement un webhook qui échoue trop souvent — corrigez la cause, testez à nouveau, puis enregistrez pour réinitialiser.

Aller plus loin

• Vue d'ensemble Développeurs — les deux briques d'intégration
• Clés API — lecture de données à la demande