Webhooks

Les webhooks permettent à un système externe de recevoir des notifications en temps réel lorsqu'un événement se produit dans ProcureSwift — par exemple, lorsqu'un bon de commande est créé, lorsque le statut d'une facture change, ou lorsqu'un devis est reçu. Au lieu d'interroger l'API à intervalles réguliers, le système externe enregistre une URL et ProcureSwift envoie un payload JSON à cette URL chaque fois qu'un événement souscrit se produit.

Où trouver cette fonctionnalité

Dans le menu principal, ouvrez Webhooks (/webhooks). Cette page requiert la permission Webhooks / View.

Événements disponibles

Une souscription peut écouter un ou plusieurs des événements suivants :

• purchase_order.created
• purchase_order.status_changed
• invoice.created
• invoice.status_changed
• rfq.published
• rfp.published
• delivery_note.created
• quotation.received
• proposal.received

Créer une souscription webhook

1. Cliquez sur Ajouter un webhook.
2. Remplissez le formulaire :
   • URL du webhook — un endpoint HTTPS accessible publiquement qui recevra les payloads d'événements. Obligatoire.
   • Événements — cochez au moins un événement auquel souscrire. Le webhook est déclenché uniquement pour les événements cochés.
3. Cliquez sur Créer.

Affichage unique du secret

Immédiatement après la création, le secret de signature du webhook est affiché une seule fois dans une boîte de dialogue de confirmation. Copiez-le maintenant et conservez-le de manière sécurisée sur le système récepteur — la plateforme ne l'affichera plus jamais. Ce secret est nécessaire pour vérifier que les requêtes entrantes proviennent bien de ProcureSwift (voir Vérification de la signature ci-dessous).

Gérer les souscriptions

Le tableau Abonnements sur /webhooks affiche : l'URL, les événements, le statut, la date du dernier déclenchement, les échecs consécutifs et la date de création.

Actions disponibles par ligne :

• Basculement de statut — activez ou désactivez une souscription sans la supprimer. Les webhooks désactivés cessent de recevoir des événements, mais leur configuration est conservée.
• Modifier (icône crayon) — modifier l'URL ou la liste des événements souscrits.
• Supprimer (icône corbeille) — supprimer définitivement la souscription.

La colonne Échecs consécutifs comptabilise les tentatives de livraison consécutives en échec. Une valeur non nulle signifie que l'endpoint récepteur rejette les requêtes ou est inaccessible. Un nombre élevé d'échecs consécutifs peut amener la plateforme à réduire la fréquence des envois ou à désactiver automatiquement le webhook.

Vérification de la signature (HMAC)

Chaque requête webhook inclut un en-tête de signature calculé à partir du corps de la requête à l'aide du secret de signature de la souscription. Le système récepteur doit vérifier cette signature avant de faire confiance au payload — sans cette vérification, toute personne connaissant l'URL pourrait envoyer de faux événements.

Le flux de vérification de base côté récepteur :

1. Lire le corps brut de la requête.
2. Calculer HMAC-SHA256(secret, body).
3. Comparer le résultat, en temps constant, avec l'en-tête de signature de la requête.
4. Rejeter la requête en cas de non-correspondance.

Conservez le secret dans la configuration d'environnement du récepteur — jamais dans le code source versionné.

Nouvelles tentatives

Si l'endpoint récepteur renvoie un code de statut non-2xx ou expire, la plateforme retente la livraison selon un calendrier avec délai exponentiel. La colonne Dernier déclenchement affiche la tentative la plus récente (réussie ou non) et la colonne Échecs consécutifs indique le nombre de tentatives consécutives échouées depuis le dernier succès. Une livraison réussie remet le compteur d'échecs à zéro.

Rotation du secret

Le secret de signature est généré lors de la création du webhook et affiché une seule fois. Pour le faire pivoter, supprimez la souscription et créez-en une nouvelle (ce qui génère un nouveau secret), puis mettez à jour le secret sur le système récepteur. Coordonnez ce changement afin que le système récepteur accepte le nouveau secret avant que l'ancienne souscription ne soit supprimée.

Conseils

• Utilisez Modifier pour ajouter de nouveaux types d'événements à une souscription existante plutôt que de créer un webhook distinct pour chaque événement.
• Rendez le récepteur idempotent — la plateforme peut effectuer de nouvelles tentatives, de sorte que le même événement pourrait arriver plusieurs fois. Utilisez l'identifiant d'événement dans le payload pour dédupliquer.
• Répondez avec 200 OK dès que le payload est persisté, et traitez-le de manière asynchrone. Des handlers à longue durée d'exécution peuvent provoquer des nouvelles tentatives.
• Surveillez la colonne Échecs consécutifs ou configurez une alerte lorsqu'elle devient non nulle.

Permissions

Action	Permission requise
Consulter les souscriptions	Webhooks / View
Ajouter un webhook	Webhooks / Create
Modifier un webhook, activer/désactiver	Webhooks / Update
Supprimer un webhook	Webhooks / Delete

Guides associés

• Clés API et journaux d'audit — pour les appels API sortants de vos systèmes vers ProcureSwift.