Simuler un événement webhook

Envoie au point de réception d'un webhook un événement de test au type et au payload choisis pour valider la prise en charge d'une forme d'événement précise.

2 min de lectureTélécharger en PDF

Requête exemple

{
  "data": {
    "geo_blocked": false,
    "transfer_id": "tr_8f3a2b1c9d4e",
    "country_code": "FR",
    "downloaded_at": "2026-06-05T10:42:00Z"
  },
  "event_type": "transfer.downloaded"
}

Réponse exemple

{
  "note": "The webhook is subscribed to this event_type - your receiver should handle this branch.",
  "delivery": {
    "error": null,
    "status": 200,
    "duration_ms": 184,
    "body_preview": "{\"received\":true}"
  },
  "event_id": "b9f1c0d2-3a4e-4c5f-9012-7d8e6f1a2b3c",
  "event_type": "transfer.downloaded",
  "webhook_id": "wh_5c2e9a7b14f0",
  "simulated_payload": {
    "id": "b9f1c0d2-3a4e-4c5f-9012-7d8e6f1a2b3c",
    "data": {
      "geo_blocked": false,
      "transfer_id": "tr_8f3a2b1c9d4e",
      "country_code": "FR",
      "downloaded_at": "2026-06-05T10:42:00Z"
    },
    "test": true,
    "type": "transfer.downloaded",
    "object": "event",
    "created": 1749120120,
    "simulated": true
  },
  "subscribed_to_event_type": true
}

POST/v1/webhooks/{id}/simulateDéclenche une livraison de test signée vers l'URL du webhook avec un type d'événement et des données entièrement choisis par l'appelant.

Cet endpoint permet de cibler un `event_type` précis et d'injecter un payload personnalisé (data) afin de tester la façon dont votre récepteur gère une forme d'événement donnée (par exemple transfer.downloaded avec un country_code particulier ou geo_blocked). Il se distingue de /v1/webhooks/{id}/test, qui se contente d'envoyer un ping ou un échantillon par défaut pour vérifier que l'URL répond. La requête construit une enveloppe d'événement signée, la livre par POST à l'URL configurée du webhook (timeout de 10 secondes), puis renvoie le résultat de cette livraison. La simulation aboutit même si le webhook n'est pas abonné à ce type d'événement: la réponse signale alors que, en production, cet événement ne serait pas déclenché.

Authentification

Requiert une clé API valide disposant du scope webhooks:manage. La requête est soumise aux quotas de débit par espace de travail (classe write) et à l'idempotence standard via l'en-tête Idempotency-Key.

Paramètres de chemin

Champ	Type	Requis	Description
id	string	Oui	Identifiant du webhook à simuler. Il doit appartenir à l'espace de travail de la clé API, sinon une erreur `not_found` est renvoyée.

Corps de la requête

Champ	Type	Requis	Description
event_type	string	Oui	Type d'événement à simuler. Doit faire partie du catalogue d'événements valides (`VALID_EVENT_TYPES`), par exemple `transfer.downloaded`. Une valeur vide ou inconnue déclenche `validation_error`.
data	object	Non	Payload personnalisé injecté dans `envelope.data`. S'il est absent ou n'est pas un objet, un objet vide `{}` est utilisé.

Réponse

La réponse renvoie webhook_id, event_id (UUID généré pour la simulation), event_type et simulated_payload (l'enveloppe complète effectivement signée et livrée). Le champ subscribed_to_event_type indique (booléen) si le webhook est abonné à ce type d'événement dans sa liste events. L'objet delivery détaille le résultat de l'appel HTTP vers l'URL du récepteur: status (code HTTP renvoyé, 0 en cas d'échec réseau ou de timeout), duration_ms, body_preview (500 premiers caractères du corps de réponse) et error (message d'erreur réseau ou null). Le champ note explicite en clair si la livraison correspondrait à un événement réellement déclenché en production.

Erreurs

Code	Quand	Résolution
400 validation_error	`event_type` absent/vide, ou type inconnu absent du catalogue.	Fournir un `event_type` valide. Listez les valeurs disponibles via le catalogue d'événements (familles d'événements).
404 not_found	Aucun webhook avec cet `id` dans l'espace de travail.	Vérifier l'identifiant du webhook et qu'il appartient bien à l'espace de travail de la clé.
401 unauthorized	Clé API absente ou invalide.	Transmettre une clé API valide dans l'en-tête `Authorization`.
403 forbidden	La clé ne dispose pas du scope `webhooks:manage`.	Utiliser une clé portant le scope `webhooks:manage`.
429 rate_limited	Quota de débit de l'espace de travail dépassé (endpoints `write`).	Patienter selon l'en-tête `Retry-After` puis réessayer.
500 internal_error	Erreur de lecture du webhook en base.	Réessayer; si l'erreur persiste, contacter le support avec le `request_id`.

Voir aussi

POST /v1/webhooks/{id}/test — envoyer un simple ping pour confirmer que l'URL répond.
GET /v1/webhooks/{id} — consulter la configuration et la liste events du webhook.
POST /v1/webhooks/{id}/rotate-secret — faire tourner le secret de signature du webhook.