Webhooks Hubflow

Version résumée. La documentation complète (catalogue détaillé, exemples de signature) est à restaurer à partir du fichier webhooks.html d'origine.

Soyez prévenu en temps réel de ce qui se passe dans votre espace (dépôt créé, fichier reçu, destinataire qui termine) sans interroger l'API en boucle.

1. Principe

Vous déclarez une URL et la liste des événements qui vous intéressent. Dès qu'un de ces événements survient, Hubflow envoie un POST JSON signé à votre URL. L'émission est best-effort : si votre serveur est indisponible, l'action chez Hubflow aboutit quand même, la livraison est enregistrée et rejouée automatiquement. Les webhooks sont cloisonnés par espace.

2. Créer un endpoint

Le secret sert à vérifier la signature : conservez-le côté serveur, et faites-le tourner quand vous voulez.

3. Format des événements

Chaque livraison est un POST dont le corps contient deux clés : type (le type d'événement) et data (l'objet concerné, dans la même représentation que l'API publique). Quand une action porte sur plusieurs objets, data est un tableau. Le contexte de la livraison voyage dans les en-têtes.

4. Catalogue des événements

• Dépôts : deposit.created, deposit.completed…
• Pièces et destinataires : deposit.directory.created, deposit.directory.completed…
• Fichiers : upload.created, upload.refused…
• Envois : send.signed…

5. Vérifier la signature

Chaque requête est signée en HMAC-SHA256 avec le secret de l'endpoint. Recalculez la signature sur le corps brut et comparez-la à celle de l'en-tête avant de traiter l'événement.

6. Réessais et désactivation

Une réponse 2xx en moins de 5 secondes compte comme un succès. Sinon, la livraison est rejouée selon un calendrier croissant ; un endpoint en échec répété est désactivé automatiquement.

7. Bonnes pratiques

Répondez immédiatement et traitez l'événement en tâche de fond. Rendez vos traitements idempotents : un même événement peut arriver deux fois.