Webhooks

Les webhooks permettent à vos systèmes de réagir à ce qui se passe dans freedam au lieu d’interroger sans cesse. Quand un média termine son import, qu’un partage est créé ou qu’un gros traitement se termine, freedam notifie en quelques secondes une adresse web que vous choisissez – votre CMS peut ainsi récupérer la nouvelle image principale, votre bot Slack annoncer le dossier de campagne, ou votre pipeline lancer l’étape suivante, sans que personne n’actualise une page.

Ce qu’ils font

Vous enregistrez une ou plusieurs adresses et choisissez les événements que chacune doit recevoir. Les événements couvrent les principaux moments de la bibliothèque :

• Médias – créé, modifié, supprimé, restauré
• Collections – créée, modifiée, supprimée
• Partages – créé, révoqué
• Pipelines – la fin d’un lot d’imports, ou la fin d’un traitement en arrière-plan
• Test – un événement d’essai que vous pouvez déclencher à la demande pour vérifier votre configuration

Chaque notification contient le type d’événement, le moment où il s’est produit et les détails du média, de la collection ou du partage concerné.

Comment ça marche

Vous configurez les endpoints dans la zone d’administration sous API → Webhooks (ou via l’API). Chaque endpoint reçoit un secret de signature, affiché une seule fois – votre système l’utilise pour confirmer que les notifications reçues viennent bien de votre instance freedam et ne sont ni falsifiées ni rejouées. Si vous utilisez le SDK TypeScript, cette vérification tient en un seul appel.

La livraison est conçue pour être fiable. Si votre système est brièvement indisponible ou lent à répondre, freedam retente la notification plusieurs fois au cours des heures suivantes, en espaçant les essais. Si un endpoint échoue en permanence, il est désactivé automatiquement plutôt que sollicité à l’infini.

Et quand quelque chose se passe mal, inutile de fouiller dans les journaux du serveur. Chaque endpoint conserve un historique des livraisons – chaque tentative récente avec son résultat, sa durée et la réponse de votre serveur – visible dans l’interface d’administration. Vous pouvez aussi envoyer un événement de test à tout moment pour vérifier une nouvelle configuration avant que le trafic réel n’arrive.

À savoir

• Les endpoints doivent utiliser HTTPS et répondre rapidement – accusez réception d’abord, faites le gros du travail ensuite.
• Les secrets se renouvellent proprement. Vous pouvez émettre un nouveau secret de signature à tout moment, et l’ancien cesse aussitôt de fonctionner. Renouvelez-le quand un collègue part ou après une fuite présumée.
• Vous pouvez mettre en pause sans supprimer – désactivez un endpoint pour le faire taire tout en conservant sa configuration.
• Gérer les webhooks via l’API utilise les mêmes tokens et permissions que tout le reste.

Le contrat technique complet – en-têtes, formes des charges utiles et exemples de vérification – se trouve dans la documentation de l’API. Envie de voir ce que cela donne de bout en bout ? Essayez la démo.