Thème
Webhooks
La plateforme notifie les organisations émettrices de l'avancement de leurs transmissions batch par des webhooks HTTP signés, livrés par la passerelle de webhooks intégrée (Svix). Chaque organisation enregistre un ou plusieurs endpoints (URLs de réception) ; la plateforme y pousse les événements avec ré-essais automatiques et signature HMAC.
Deux écrans couvrent le sujet côté administrateur :
| Écran | URL | Vocation |
|---|---|---|
| Suivi des évènements webhook | /notifications | Recherche cross-organisation des notifications émises par la plateforme. Menu Suivi des activités ▸ Webhook events. |
| Onglet Webhooks de la fiche organisation | /organizations/{code}/webhooks | Gestion des endpoints de réception d'une organisation (URL, filtres, secret de signature). |
La synchronisation du catalogue d'événements se pilote depuis le Catalogue de services.
Fonctionnement
- Qui émet : le module
mi-transmission(flux batch asynchrones). Les modules synchrones (mi-consultation-droits,mi-adjudication) n'émettent pas de webhook — l'appelant a déjà la réponse dans la foulée. - Qui reçoit : l'organisation émettrice du batch, sur ses endpoints enregistrés. Une organisation qui émet ses batches par SFTP ne reçoit pas de webhook : elle reçoit un fichier de retour déposé dans son dossier
outboxSFTP. - Catalogue : chaque module déclare son catalogue d'événements à son enregistrement sur la plateforme ; ce catalogue alimente le sélecteur de filtres des endpoints et est miroité vers la passerelle.
- Fiabilité : émission garantie at-least-once (outbox côté module). Chaque événement porte un Event ID stable : une re-livraison du même événement porte le même identifiant, ce qui permet au partenaire de dédupliquer.
- Ré-essais : tant que l'endpoint ne répond pas en 2xx, la passerelle ré-essaie automatiquement avec des délais croissants (de quelques secondes à plusieurs heures). Chaque tentative est visible dans le volet de détail.
Événements du catalogue
Six événements, tous émis par mi-transmission :
| Événement | Catégorie | Émis quand |
|---|---|---|
batch.accepted | ingestion | Batch REST validé et découpé — le fan-out vers les destinations démarre. |
batch.child.delivered | delivery | Un lot a été livré à une destination (réponse 2xx REST, ou dépôt de fichier SFTP). |
batch.child.rejected | delivery | La destination a refusé le lot (erreur 4xx applicative). |
batch.child.failed | delivery | Échec définitif de livraison après épuisement des ré-essais. |
batch.completed | delivery | Tous les lots du batch ont un état terminal — résumé final avec compteurs. |
batch.unroutable | operational | Configuration de la destination introuvable au moment du dispatch. |
Pas de batch.rejected
Un rejet de validation à l'ingestion REST est connu synchroniquement (réponse 4xx immédiate, ou 202 avec childCount: 0) : il n'est pas dupliqué en webhook. Les webhooks ne notifient que des issues asynchrones.
Contenu du payload
| Champ | Présence | Description |
|---|---|---|
eventType | toujours | Code de l'événement (repris dans le corps pour faciliter le traitement). |
correlationId | toujours | Identifiant de la transmission — la même clé que sur la page Transmissions. |
batchId / childId | selon l'événement | Identifiants du batch et du lot destination. |
destinationHandle | événements batch.child.* et batch.unroutable | Code de l'organisation destination concernée. |
resourceCode | événements enfant | Code de ressource du flux (POPULATION…). |
status / error | événements enfant | État du lot et détail d'erreur le cas échéant (ex. HTTP 422). |
transport | selon l'événement | Canal concerné (REST / SFTP). |
recordCount / destinationCount | batch.accepted | Volumétrie du batch et nombre de destinations. |
delivered / rejected / failed / total | batch.completed | Compteurs finaux du batch. |
Écran « Suivi des évènements webhook » (/notifications)
URL : /notifications • Menu : Suivi des activités ▸ Webhook events • Permission requise : notification_read_all (administrateur plateforme uniquement)
Filtres
- Organisation — obligatoire : la liste affiche les notifications émises vers une organisation à la fois. À l'ouverture, la page pré-sélectionne l'organisation dont l'activité webhook est la plus récente (bandeau « Vous consultez les webhooks émis vers … »).
- Période — Dernier jour, 7 / 30 / 60 / 90 derniers jours.
- Recherche — filtre les lignes déjà chargées (correlationId, type d'événement, Message ID, Event ID).
Colonnes
| Colonne | Visible par défaut | Signification |
|---|---|---|
| Correlation ID | ✔ (épinglée) | Badge copiable — même clé que la page Transmissions. |
| Type d'événement | ✔ | Code du catalogue (batch.child.delivered…). La ligne-tête d'un groupe porte une pastille +N. |
| Module / MI source | ✔ | Module déclencheur, résolu via le catalogue (batch.* → mi-transmission). |
| Destinataire | ✔ | Organisation réceptrice des webhooks (l'émettrice du flux). |
| Message ID / Event ID | ✘ | Identifiants techniques de la passerelle (sélecteur de colonnes). |
| Horodatage | ✔ | Date et heure d'émission. |
| Actions | ✔ | 👁️ Voir les détails. |
Groupement par corrélation
Les événements d'une même transmission sont regroupés par correlationId : une ligne-tête (l'événement le plus récent) avec un bouton + qui déplie les autres événements du groupe. Le groupement s'applique aux lignes chargées — le bouton Afficher plus de résultats en pied de tableau complète les groupes (pagination par curseur, pas de total : le compteur indique « N affichées »).
Volet de détail
Double-clic sur une ligne ou 👁️ : volet avec le type d'événement, les identifiants, le Payload (JSON, bouton Copier) et la section Tentatives de livraison :
- une carte par tentative : badge de statut (Succès 🟢, En attente, En cours, Échec 🔴, Annulé), code HTTP, latence, horodatage, URL de l'endpoint visé, bloc dépliable Voir la réponse ;
- Prochaine tentative affichée quand un ré-essai est planifié ;
- bouton Rafraîchir pour recharger les tentatives.
En pied de volet, Replayer manuellement (permission webhook_replay) ré-émet la notification vers tous les endpoints actifs de l'organisation, après confirmation.
Onglet « Webhooks » de la fiche organisation
URL : /organizations/{code}/webhooks • Permission requise : webhook_read (+ webhook_create, webhook_update, webhook_delete pour agir)
Gestion des endpoints de réception de l'organisation. Fonctionnellement identique à la page Webhooks du guide organisation — s'y référer pour le détail des colonnes, du formulaire et de la gestion du secret. À retenir côté administrateur :
- Le bouton Nouveau endpoint ouvre le formulaire : URL du webhook (HTTPS, joignable par la passerelle), Description, Filtre d'eventTypes (sélection dans le catalogue — vide = tous les événements sont livrés), bascule Désactiver cet endpoint.
- À la création, le secret de signature HMAC est révélé une seule fois — à transmettre au partenaire.
- Rotater le secret : l'ancien secret reste valide 24 h pour laisser le partenaire basculer.
- Si l'organisation est inactive ou en provisioning, l'onglet passe en lecture seule (l'affichage du secret reste possible).
Voir aussi
- Catalogue de services — colonne Webhooks et synchronisation
- Transmissions — la section Notification webhook du volet de détail relie une transmission à son webhook.
- Webhooks (guide organisation) — point de vue du partenaire : réception, vérification de signature.