Livraisons webhook
L'écran Livraisons webhook vous permet de lire les webhooks signés reçus par les connecteurs, de savoir si leur signature était valide et pourquoi une livraison a été rejetée. Chemin dans le portail : /capabilities/webhooks. Les développeurs et les intégrateurs l'utilisent pour mettre au point les webhooks d'un système métier ; les responsables sécurité l'utilisent pour repérer les livraisons falsifiées ou rejouées. L'écran est en lecture seule et dessiné par portal/src/screens/capabilities.tsx.
Ce que montre l'écran
- Tableau Livraisons, lu par
GET /v1/webhooks/deliveries(les 50 lignes les plus récentes ; cette route n'a pas de curseur). Colonnes : Connecteur, Identifiant de livraison, Signature valide, Statut (accepted,rejected,duplicate), Raison, Reçu. - Filtre Connecteur (nom du connecteur), puis Filtrer.
- Liste vide : Aucune livraison webhook, avec l'aide Les livraisons apparaissent quand un connecteur reçoit un webhook signé.
- Un clic sur une ligne, ou Voir le détail, affiche tous les champs de la ligne dans un panneau latéral.
La colonne Raison prend ces valeurs (services/control-plane/src/eai/domains/connectors/service.py) :
| Raison | Statut | Signification |
|---|---|---|
bad_signature | rejected | L'en-tête X-EAI-Signature ne correspond pas au contenu. |
no_secret | rejected | Aucun secret de webhook n'a pu être lu pour le connecteur (ni identifiant webhook_secret, ni spec.webhooks.secret_ref). |
timestamp_outside_window | rejected | L'horodatage de la signature s'écarte de plus de 5 minutes de l'horloge du Control Plane. |
duplicate_delivery | duplicate | Le même identifiant de livraison a déjà été accepté. |
prompt_injection_blocked | rejected | Le contenu ressemble à une injection de prompt. |
| vide | accepted | La livraison a été acceptée et publiée comme événement. |
Actions
| Bouton ou action | Ce qu'il fait | Appel d'API | Rôles |
|---|---|---|---|
| Actualiser (icône) | Recharge la liste. | GET /v1/webhooks/deliveries | Tout membre du tenant |
| Filtrer | Garde les livraisons d'un connecteur. | GET /v1/webhooks/deliveries avec connector | Tout membre du tenant |
| Clic sur une ligne ou Voir le détail | Affiche la ligne de la livraison. | Aucun | Tout membre du tenant |
| Réessayer (état d'erreur) | Relance la lecture qui a échoué. | Même appel | Mêmes rôles |
Un système métier livre un webhook avec POST /v1/webhooks/{connector} et ces en-têtes :
X-EAI-Tenant: <tenant-slug>
X-EAI-Signature: t=<unix-time>,v1=<hex-hmac>
X-EAI-Delivery: <delivery-id>
<tenant-slug> : slug de votre tenant. <unix-time> : heure de la livraison en secondes (elle peut aussi venir dans un en-tête X-EAI-Timestamp séparé). <hex-hmac> : HMAC-SHA256, en hexadécimal, de <unix-time>. suivi du corps brut, avec pour clé le secret de webhook du connecteur (sha256= est accepté à la place de v1=). <delivery-id> : identifiant unique de la livraison (absent, l'horodatage et l'empreinte du contenu sont utilisés). La fenêtre anti-rejeu est de 5 minutes. Une livraison acceptée est publiée sur le sujet connectors.<connector>.webhook.
Rôles
La liste demande seulement un tenant (services/control-plane/src/eai/domains/connectors/routes.py) ; l'écran n'offre aucune action d'écriture. La route de webhook elle-même n'est pas appelée avec une session d'utilisateur : elle authentifie l'émetteur par la signature et n'accepte de livraison que pour un connecteur actif dont le manifeste active les webhooks. Le secret de webhook se dépose avec l'action Identifiants de l'écran Connecteurs (type webhook_secret), par tenant_admin ou security_officer.
Tâches courantes
Mettre au point un webhook qui ne déclenche rien
- Filtrer sur le connecteur. Chaque livraison est journalisée, acceptée ou non. Saisissez le nom du connecteur dans Connecteur et cliquez sur Filtrer. Résultat attendu : les livraisons du connecteur, les plus récentes d'abord. En cas d'échec : Aucune livraison webhook signifie que rien n'a atteint le Control Plane ; vérifiez l'URL et l'en-tête
X-EAI-Tenantde l'émetteur. - Lire la raison. La raison indique le contrôle qui a échoué. Lisez Signature valide, Statut et Raison de la dernière ligne. Résultat attendu :
acceptedavec une raison vide. En cas d'échec :bad_signatureouno_secretsignifie que le secret diffère ou manque ; déposez-le de nouveau avec Identifiants (typewebhook_secret). - Vérifier l'événement. Une livraison acceptée est publiée sur le sujet
connectors.<connector>.webhook. Ouvrez l'écran Déclencheurs et vérifiez qu'un déclencheur écoute ce sujet. Résultat attendu : une exécution démarre sur l'écran Exécutions. En cas d'échec : comparez le filtre du déclencheur avec le contenu.
Repérer les livraisons rejouées
- Chercher les doublons. Un rejeu réutilise une ancienne livraison. Lisez les lignes au statut
duplicateou à la raisontimestamp_outside_window. Résultat attendu : peu ou aucune. En cas d'échec : de nombreuses lignes venant d'une même source signalent une tentative de rejeu ; prévenez l'équipe sécurité.
Dépannage
| Symptôme | Cause | Correction |
|---|---|---|
L'émetteur reçoit invalid_signature (401) | Signature fausse, secret absent, ou tenant inconnu ou inactif. | Vérifiez le secret, la chaîne signée <unix-time>.<body> et l'en-tête X-EAI-Tenant. |
L'émetteur reçoit tenant_required (400) | L'en-tête X-EAI-Tenant manque. | Ajoutez l'en-tête avec le slug du tenant. |
L'émetteur reçoit connector_not_found (404) | Le connecteur n'existe pas, n'est pas actif, ou son manifeste n'active pas les webhooks. | Activez les webhooks dans le manifeste et passez le connecteur à active. |
L'émetteur reçoit webhook_replay (401), raison timestamp_outside_window | L'horloge de l'émetteur dérive, ou la livraison est rejouée. | Synchronisez l'horloge de l'émetteur. |
L'émetteur reçoit webhook_duplicate (409), statut duplicate | Le même identifiant de livraison a déjà été accepté. | Envoyez un nouveau X-EAI-Delivery pour chaque événement. |
Raison prompt_injection_blocked | Le contenu porte un texte qui ressemble à une injection de prompt. | Nettoyez le contenu à la source. |