Webhooks

URL : /organizations/{orgId}/webhooks • Menu : Suivi des activités ▸ Webhooks • Permission requise : webhook_read (+ webhook_create, webhook_update, webhook_delete pour agir)

Si votre organisation émet des transmissions batch par REST, la plateforme vous notifie de leur avancement par des webhooks HTTP signés : validation du batch, livraison de chaque lot aux destinations, échecs éventuels, puis résumé final. Cette page vous permet d'enregistrer les endpoints (URLs de votre SI) qui recevront ces notifications.

Émetteurs SFTP

Si vous déposez vos batches par SFTP, vous ne recevez pas de webhook : le compte-rendu est un fichier de retour déposé dans votre dossier outbox SFTP.

Événements reçus

Événement	Signification
batch.accepted	Votre batch a été validé et découpé — la distribution vers les destinations démarre.
batch.child.delivered	Un lot a été livré à une destination.
batch.child.rejected	Une destination a refusé le lot (erreur applicative).
batch.child.failed	Échec définitif de livraison vers une destination après les ré-essais de la plateforme.
batch.completed	Tous les lots du batch sont traités — résumé final (delivered / rejected / failed / total).
batch.unroutable	La configuration d'une destination est introuvable — contactez le support.

Chaque payload contient au minimum eventType et correlationId (la clé de traçabilité que vous retrouvez sur la page Transmissions), plus les champs propres à l'événement (batchId, destinationHandle, status, error…).

Liste des endpoints

Le compteur en haut affiche le nombre d'endpoints. Recherche par URL ou description, bouton rafraîchir, bouton Nouveau endpoint (permission webhook_create).

Colonne	Signification
Statut	Actif (🟢) ou Désactivé (⚪). Un endpoint désactivé ne reçoit aucune livraison.
URL	L'URL de réception (host en gras + URL complète).
Description	Libellé interne, visible uniquement dans la console.
Filtres	Badge « N types » (survolez pour la liste) ou « Tous les événements » si aucun filtre.
Date de création	Date d'enregistrement de l'endpoint.
Actions	👁️ Afficher le secret HMAC • 🔄 Rotater le secret • 🖊️ Modifier • 🗑️ Supprimer.

Organisation inactive ou en provisioning

Si votre organisation n'est pas active, la page passe en lecture seule (création, modification, rotation et suppression désactivées). L'affichage du secret reste possible.

Créer ou modifier un endpoint

Le formulaire « Nouvel endpoint webhook » comporte :

• URL du webhook (requis) — URL HTTPS publique joignable par la passerelle de la plateforme (ex. https://partner.example.com/webhooks/asaci).
• Description (optionnelle) — libellé interne.
• Filtre d'eventTypes (optionnel) — sélection dans le catalogue déclaré par les modules. Vide = tous les événements sont livrés.
• Désactiver cet endpoint — bascule pour suspendre les livraisons sans supprimer la configuration.

À la création, le secret de signature est affiché une seule fois dans un volet dédié : copiez-le et transmettez-le à votre équipe technique — il ne sera plus consultable en clair que via l'action Afficher le secret HMAC.

Secret de signature et rotation

Chaque endpoint possède un secret HMAC (préfixé whsec_) qui sert à vérifier l'authenticité des livraisons.

• Afficher le secret HMAC (👁️) — révèle le secret courant (masqué par défaut, boutons Afficher / Copier).
• Rotater le secret (🔄) — génère un nouveau secret après confirmation. L'ancien secret reste accepté pendant 24 h pour vous laisser basculer sans coupure.

Recevoir et vérifier une livraison

Chaque livraison est un POST JSON portant les en-têtes webhook-id, webhook-timestamp et webhook-signature (et leurs alias svix-*), conformes au standard Standard Webhooks.

Vérification de la signature :

1. Reconstituez le contenu signé : <webhook-id>.<webhook-timestamp>.<corps brut de la requête>.
2. Calculez le HMAC-SHA256 de ce contenu avec le secret de l'endpoint (partie base64 après le préfixe whsec_), encodé en base64.
3. Comparez au header webhook-signature (il peut contenir plusieurs signatures séparées par des espaces, chacune préfixée v1, — utile pendant les 24 h d'une rotation).
4. Rejetez les timestamps trop anciens (tolérance recommandée : 5 minutes).

Des bibliothèques officielles (Svix / Standard Webhooks) implémentent cette vérification dans la plupart des langages.

Bonnes pratiques côté récepteur :

• Répondez 2xx rapidement (accusez réception, traitez en asynchrone) — toute autre réponse déclenche des ré-essais automatiques à délais croissants.
• Dédupliquez par webhook-id : une re-livraison du même événement porte le même identifiant.

Consulter les notifications émises

Il n'existe pas de liste dédiée côté organisation. Deux points d'accès :

• Détail d'une transmission — la section « Notification webhook » du volet de détail affiche l'événement lié (type + horodatage) et le bouton Voir les détails ouvre le payload et les tentatives de livraison (statut, code HTTP, latence, réponse de votre endpoint, prochaine tentative planifiée). Voir Transmissions.

  

• Replayer manuellement (permission webhook_replay) — depuis ce même volet, ré-émet la notification vers tous les endpoints actifs de votre organisation.

Voir aussi

• Transmissions — suivi des flux et section Notification webhook.
• Diagnostiquer un échec — parcours de dépannage.