Webhook

Comment fonctionne un webhook

1. Enregistrement. Vous donnez au système source l’URL d’un endpoint et la liste des événements que vous voulez recevoir.
2. Événement. Quelque chose se produit dans le système source.
3. Livraison. La source envoie une requête POST à votre URL avec un corps JSON et un en-tête de signature.
4. Accusé de réception. Votre récepteur vérifie la signature et répond avec un statut 2xx en quelques secondes. Le travail long se fait ensuite, dans une file d’attente.
5. Nouvelle tentative. Si la réponse n’est pas 2xx, ou si aucune réponse ne vient, la source réessaie après des délais croissants. Après des échecs répétés, elle désactive en général l’endpoint.

Élément	Ce que c’est
URL de l’endpoint	L’adresse de votre côté qui reçoit les livraisons
Type d’événement	Un nom comme asset.updated qui dit ce qui s’est passé
Charge utile	Le corps JSON : l’événement, un horodatage et des identifiants
Secret	Une clé partagée qui sert à signer et à vérifier chaque livraison
Journal des livraisons	L’enregistrement des tentatives, des codes de réponse et des erreurs

Webhook ou polling d’API

	Polling d’une API	Webhook
Qui lance la requête	Votre système, selon un calendrier	Le système source, quand l’événement se produit
Délai	Jusqu’à un intervalle de polling	En général quelques secondes
Charge	Beaucoup de requêtes qui ne renvoient rien de nouveau	Une requête par événement
Idéal pour	Réconciliation en masse, rapports	Réagir à chaque changement

Les deux fonctionnent ensemble. Un webhook vous dit que quelque chose a changé, et l’API vous en donne les détails. De nombreux systèmes n’envoient que des identifiants dans la charge utile, pour que le récepteur lise l’état actuel par l’API plutôt que de se fier à une copie peut-être déjà périmée.

Sécuriser les webhooks

• Vérifier la signature. La plupart des fournisseurs signent chaque livraison avec HMAC (RFC 2104, IETF, 1997) en SHA-256 et le secret partagé. Calculez la même valeur sur le corps brut et comparez les deux en temps constant.
• Contrôler l’horodatage. Rejetez les livraisons signées depuis plus de quelques minutes, pour qu’une requête interceptée ne puisse pas être rejouée plus tard.
• Utiliser HTTPS pour l’endpoint.
• Rendre le traitement idempotent. Les nouvelles tentatives font qu’un même événement peut arriver deux fois. Le traiter une seconde fois ne doit pas créer un second enregistrement.
• Renouveler le secret quand une personne qui y avait accès part ou qu’une fuite est soupçonnée.
• Côté émetteur, refuser les adresses privées. Un système qui livre à n’importe quelle URL peut être dirigé vers des services internes (server-side request forgery) : un émetteur prudent ne livre donc qu’à des hôtes de l’internet public.

Les webhooks dans le travail du DAM et du marketing

• Site web et CMS. Quand une photo produit validée est mise à jour, le récepteur de l’équipe web vide le cache du CDN pour que les fiches produit affichent le nouveau fichier.
• Informations produit. Quand un nouveau packshot termine l’ingestion, un récepteur l’associe au bon SKU dans le système d’information produit.
• Validation. Quand un média atteint « Approuvé » dans un workflow, un récepteur publie dans le canal de discussion de l’équipe ou lance une tâche de traduction.
• Activité des partenaires. Quand un distributeur ouvre un lien de partage ou télécharge depuis celui-ci, le CRM enregistre l’activité sur le compte pour l’équipe commerciale.
• Imports d’agence. Quand un lot d’import d’une agence est terminé, un contrôle qualité démarre.

Erreurs courantes : faire un travail long avant de répondre, ce qui provoque des délais dépassés, des nouvelles tentatives et des doublons ; analyser le JSON avant de vérifier la signature, ce qui change les octets couverts par la signature ; et ne pas remarquer qu’un endpoint a été désactivé par l’émetteur après des échecs répétés.

Les webhooks dans Freedam

• Les endpoints sont enregistrés par l’API REST avec un token qui a la permission Gérer les webhooks. Les événements couvrent les médias (créés, mis à jour, supprimés, téléchargés), les collections et les médias ajoutés ou retirés, les liens de partage (créés, ouverts ou téléchargés depuis), les lots d’import (terminés ou en échec) et les changements de statut de workflow, ou * pour tous.
• Chaque livraison est un POST signé : un HMAC-SHA256 de l’horodatage et du corps brut, envoyé dans les en-têtes X-Freedam-Signature-256 et X-Freedam-Timestamp. Le SDK TypeScript inclut une fonction de vérification. Le secret est affiché une seule fois et peut être renouvelé.
• Votre récepteur a 30 secondes pour répondre. Une livraison en échec est retentée jusqu’à 5 fois, après 10 secondes, 1 minute, 5 minutes et 30 minutes. Après 10 tentatives en échec consécutives, l’endpoint est désactivé.
• Un endpoint ne reçoit que les événements sur les éléments que son propriétaire pourrait voir par l’API, si bien qu’un webhook ne peut pas révéler des médias masqués par le contrôle d’accès.
• Les livraisons ne vont qu’à des hôtes de l’internet public. L’URL est vérifiée quand l’endpoint est enregistré, puis à chaque livraison, après la résolution du nom d’hôte.
• Les administrateurs voient chaque endpoint dans l’onglet Webhooks de la page Gestion de l’API, avec un graphique de santé des webhooks, et peuvent désactiver, réactiver ou supprimer un endpoint, ou remettre à zéro son compteur d’échecs.

Détails : la page développeurs webhooks et la référence des webhooks dans la documentation Freedam (en anglais).

Questions fréquentes

Quelle différence entre un webhook et une API ?

Une API répond aux requêtes que votre système envoie. Un webhook est une requête que l’autre système vous envoie quand quelque chose se produit. Les intégrations utilisent en général les deux : le webhook annonce le changement, et un appel d’API récupère les données actuelles.

Qu’est-ce qu’une URL de webhook ?

C’est l’adresse du récepteur que vous exploitez, par exemple une route de votre propre application ou d’un outil d’automatisation. Le système source y envoie ses livraisons. Elle doit être accessible depuis internet et n’accepter que les requêtes avec une signature valide.

Que se passe-t-il si mon endpoint de webhook est hors service ?

L’émetteur réessaie pendant un temps, puis désactive en général l’endpoint. Les événements survenus pendant la désactivation ne sont souvent pas mis en file : après une panne, comparez vos données avec la source par son API pour rattraper ce que vous avez manqué.