Requête exemple
Réponse exemple
Envoie une livraison de test signée vers l'URL configurée d'un endpoint webhook, puis renvoie de façon synchrone la réponse du récepteur (code HTTP, durée et aperçu du corps). C'est l'outil de diagnostic pour valider qu'une URL est joignable, que la signature est correctement vérifiée côté récepteur et que le handler répond. Comportement notable : la requête sortante porte toujours l'en-tête X-Coffrify-Test-Delivery: true, ce qui permet au récepteur de distinguer un test d'un événement réel et de court-circuiter ses flux métier pendant l'intégration. Le payload est signé deux fois : au format Standard Webhooks (en-tête webhook-signature, signature de <id>.<timestamp>.<body> en base64) et au format legacy Coffrify (en-tête X-Coffrify-Signature, signature de <timestamp>.<body> en hexadécimal). Un timeout de 10 secondes s'applique à l'appel sortant ; au-delà, la requête est abandonnée et l'erreur est remontée dans le champ error (le test ne renvoie alors pas d'erreur HTTP côté API).
Authentification
Requiert un jeton (clé cof_live_ / cof_test_, clé restreinte cof_rk_* ou jeton MCP cof_mcp_*) portant le scope webhooks:manage. Un jeton sans ce scope reçoit une erreur 403 scope_missing. L'endpoint webhook ciblé doit appartenir au même workspace que celui résolu depuis le jeton ; sinon il est traité comme introuvable.
Corps de la requête
Le corps JSON est entièrement optionnel : sans corps, un événement ping vide est envoyé.
| Champ | Type | Requis | Description |
|---|---|---|---|
| event_type | string | Non | Type d'événement à simuler. Doit valoir ping ou une entrée valide du catalogue d'événements (VALID_EVENT_TYPES). Valeur par défaut : ping. Toute autre valeur renvoie 400 validation_error. |
| data | object | Non | Charge utile métier placée dans payload.data de l'événement envoyé. Toute valeur non-objet (string, number, null) est ignorée et remplacée par un objet vide {}. |
L'identifiant du webhook (id) est pris dans le chemin de l'URL, pas dans le corps. Le payload réellement transmis au récepteur a la forme { id, object: "event", type, created, data, test: true }, accompagné des en-têtes de signature et des en-têtes X-Coffrify-Event-Id / X-Coffrify-Event-Type.
Réponse
La réponse récapitule l'issue de la livraison de test. status est le code HTTP renvoyé par le récepteur (ou 0 si l'appel a échoué avant toute réponse, par exemple sur timeout ou DNS injoignable). duration_ms mesure la durée totale de l'aller-retour. body_preview contient les 500 premiers caractères du corps de réponse du récepteur. error est null en cas d'appel réussi, ou le message d'erreur réseau/timeout sinon. event_id est l'UUID de l'événement de test généré (à retrouver dans les en-têtes webhook-id / X-Coffrify-Event-Id), et test_delivery vaut toujours true.
Erreurs
| Code | Quand | Comment résoudre |
|---|---|---|
| 400 validation_error | id manquant dans l'URL, ou event_type n'est ni ping ni une entrée valide du catalogue. | Vérifier l'URL et choisir un event_type listé par GET /v1/webhooks/event-catalog. |
| 401 invalid_api_key | Jeton absent, mal formé, révoqué ou expiré. | Fournir un jeton valide dans l'en-tête Authorization. |
| 403 scope_missing | Le jeton ne porte pas le scope webhooks:manage. | Émettre un jeton incluant webhooks:manage. |
| 404 not_found | Aucun webhook avec cet id dans le workspace du jeton. | Vérifier l'id via GET /v1/webhooks et confirmer le bon workspace. |
| 500 internal_error | Erreur lors de la lecture du webhook en base. | Réessayer ; si persistant, contacter le support. |
Voir aussi
POST/v1/webhooks/{id}/simulateSimule un événement de bout en bout en l'enregistrant dans la file de livraison réelle, contrairement au test synchrone.GET/v1/webhooks/event-catalogListe les valeurs d'event_type valides à passer au test.POST/v1/webhooks/{id}/rotate-secretFait tourner le secret de signature utilisé pour signer les livraisons (test inclus).