Simuler un événement webhook en environnement de test

L'API Coffrify expose deux endpoints distincts pour tester la réception de webhooks sans produire d'activité réelle. `/test` envoie un événement ping (ou un type de catalogue au choix) en une seule ligne, idéal pour vérifier que votre URL est joignable. `/simulate` va plus loin : il vous permet de cibler un event_type précis du catalogue et d'injecter un data personnalisé (par exemple transfer.geo_blocked avec un country_code particulier), afin de valider la logique métier de votre receiver. Dans les deux cas, l'en-tête X-Coffrify-Test-Delivery: true est systématiquement présent, ce qui vous permet de brancher votre receiver sur un chemin de traitement dédié sans risquer de déclencher de vrais flux.

Authentification

Ces deux endpoints requièrent le scope webhooks:manage. Transmettez votre clé API dans l'en-tête Authorization: Bearer <clé>. En environnement de test, utilisez une clé préfixée cof_test_… ; en production, cof_live_…. Les clés sandbox (cof_sandbox_…) sont également acceptées pour les environnements d'intégration continue.

Corps de la requête

Les deux endpoints acceptent un corps JSON optionnel avec les mêmes champs. Pour /test, event_type vaut "ping" par défaut si absent. Pour /simulate, event_type est obligatoire et doit correspondre à une entrée du catalogue (voir Catalogue d'événements).

Appels en pratique

# /simulate : cibler un type d'événement précis avec un payload personnalisé
curl -X POST https://api.coffrify.com/v1/webhooks/wh_01J9XXXXXXXXXXXXXXXXXX/simulate \
  -H "Authorization: Bearer cof_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "transfer.geo_blocked",
    "data": {
      "transfer_id": "tf_01J9YYYYYYYYYYYYYY",
      "country_code": "CN",
      "geo_blocked": true
    }
  }'
 
# /test : envoyer un ping rapide pour vérifier la joignabilité de l'URL
curl -X POST https://api.coffrify.com/v1/webhooks/wh_01J9XXXXXXXXXXXXXXXXXX/test \
  -H "Authorization: Bearer cof_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "ping"}'

Réponse

Les deux endpoints renvoient un objet JSON décrivant la livraison effectuée. /simulate ajoute les champs simulated_payload, subscribed_to_event_type et note absents de /test.

Réponse de `/simulate` (200 OK) :

{
  "webhook_id": "wh_01J9XXXXXXXXXXXXXXXXXX",
  "event_id": "a3f7c2d1-0e4b-4a9f-8c6e-1b2d3e4f5a6b",
  "event_type": "transfer.geo_blocked",
  "simulated_payload": {
    "id": "a3f7c2d1-0e4b-4a9f-8c6e-1b2d3e4f5a6b",
    "object": "event",
    "type": "transfer.geo_blocked",
    "created": 1749254400,
    "data": {
      "transfer_id": "tf_01J9YYYYYYYYYYYYYY",
      "country_code": "CN",
      "geo_blocked": true
    },
    "test": true,
    "simulated": true
  },
  "subscribed_to_event_type": true,
  "delivery": {
    "status": 200,
    "duration_ms": 142,
    "body_preview": "{\"received\":true}",
    "error": null
  },
  "note": "The webhook is subscribed to this event_type - your receiver should handle this branch."
}

Réponse de `/test` (200 OK) :

{
  "webhook_id": "wh_01J9XXXXXXXXXXXXXXXXXX",
  "event_id": "b5e1f3c2-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
  "event_type": "ping",
  "status": 200,
  "duration_ms": 87,
  "body_preview": "OK",
  "error": null,
  "test_delivery": true
}

En-têtes envoyés à votre receiver

Chaque livraison de test transmet les en-têtes suivants. Votre receiver peut les inspecter pour valider sa logique de vérification de signature HMAC.

Erreurs

Voir aussi

• Créer un webhook
• Catalogue des types d'événements
• Vérifier la signature HMAC d'une livraison
• Rejouer une livraison échouée
• Référence : GET /v1/webhooks/{id}/deliveries