Webhooks

Page générée depuis la spécification OpenAPI que la passerelle sert (GET /v1/openapi.json). Ne la modifiez pas à la main : elle est réécrite à chaque build.

Méthode	Chemin	Description
GET	/v1/webhooks	Lister vos endpoints de notification
POST	/v1/webhooks	Enregistrer un endpoint
POST	/v1/webhooks/test	Provoquer une livraison de test
GET	/v1/webhooks/{id}	Consulter un endpoint
PATCH	/v1/webhooks/{id}	Modifier un endpoint
DELETE	/v1/webhooks/{id}	Supprimer un endpoint
GET	/v1/webhooks/{id}/secret	Relire le secret de signature

GET /v1/webhooks

Lister vos endpoints de notification

Vos endpoints, avec leurs compteurs de livraison. consecutive_failures est le champ à regarder quand les notifications s'arrêtent : vingt échecs consécutifs suspendent un endpoint une heure, et un seul succès le réhabilite.

ⓘ Les endpoints ne sont PAS séparés entre test et production : une clé de test et une clé réelle voient les mêmes.

Réponses

• 200 — OK (WebhookList)
• 401 — Clé API manquante ou rejetée (Error)
• 403 — La clé ne porte pas le scope can_manage_webhooks (Error)
• 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

POST /v1/webhooks

Enregistrer un endpoint

⚠️ CET APPEL GARANTIT, IL NE CRÉE PAS TOUJOURS. Une URL déjà enregistrée revient en 200 au lieu d'être dupliquée, donc un script de provisionnement rejoué laisse UN endpoint et non deux recevant chaque événement en double. Le secret est rendu dans les deux cas, parce que la raison légitime de rappeler est de l'avoir perdu.

Dix endpoints par compte au maximum. subscribed_events vide = tous les événements ; sinon, parmi : payment.initiated, payment.pending, payment.success, payment.failed, payout.success, payout.failed, payout.cancelled, payout.refunded, refund.success, refund.failed, et la famille subscription.*.

Corps de la requête

Champ	Type	Requis	Description
url	string	oui	HTTPS obligatoire.
description	string	non	Pour vous y retrouver dans la liste.
subscribed_events	string[]	non	Vide = tous. Un événement hors catalogue est refusé plutôt que stocké : il attendrait une livraison que rien n'émet.

Réponses

• 200 — L'endpoint existait déjà pour cette URL (WebhookCreated)
• 201 — Endpoint créé (WebhookCreated)
• 401 — Clé API manquante ou rejetée (Error)
• 403 — La clé ne porte pas le scope can_manage_webhooks (Error)
• 422 — URL non-HTTPS, événement hors catalogue, ou dix endpoints déjà enregistrés (Error)
• 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

POST /v1/webhooks/test

Provoquer une livraison de test

Envoie un événement payment.test à TOUS vos endpoints actifs et rend le résultat de chaque livraison. Rien n'est persisté, et aucun argent n'est en jeu — c'est la façon de vérifier votre vérification de signature avant le premier vrai paiement.

ⓘ Scope can_read_transactions, pas can_manage_webhooks : l'appel ne modifie aucune configuration.

Réponses

• 200 — Résultat par endpoint
• 400 — Aucun endpoint actif vers qui livrer (Error)
• 401 — Clé API manquante ou rejetée (Error)
• 403 — La clé ne porte pas le scope can_manage_webhooks (Error)
• 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

GET /v1/webhooks/{id}

Consulter un endpoint

Le même objet que dans la liste.

Paramètres

Nom	Emplacement	Requis	Description
id	path	oui	Le numéro de l'endpoint, tel que rendu par GET /v1/webhooks.

Réponses

• 200 — OK (object)
• 401 — Clé API manquante ou rejetée (Error)
• 403 — La clé ne porte pas le scope can_manage_webhooks (Error)
• 404 — Aucun endpoint de ce numéro pour ce compte (Error)
• 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

PATCH /v1/webhooks/{id}

Modifier un endpoint

Modification PARTIELLE : seuls les champs envoyés changent. Omettre is_active ne désactive pas l'endpoint, et omettre description ne l'efface pas — ce qui n'est pas une subtilité, puisque l'inverse ferait qu'un appel renommant un endpoint arrêterait silencieusement ses propres livraisons.

is_active: false suspend les livraisons sans perdre l'endpoint ni son secret.

Paramètres

Nom	Emplacement	Requis	Description
id	path	oui	Le numéro de l'endpoint, tel que rendu par GET /v1/webhooks.

Corps de la requête

Champ	Type	Requis	Description
url	string	non	HTTPS obligatoire.
description	string	non
subscribed_events	string[]	non
is_active	boolean	non

Réponses

• 200 — OK (object)
• 401 — Clé API manquante ou rejetée (Error)
• 403 — La clé ne porte pas le scope can_manage_webhooks (Error)
• 404 — Aucun endpoint de ce numéro pour ce compte (Error)
• 422 — URL non-HTTPS ou événement hors catalogue (Error)
• 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

DELETE /v1/webhooks/{id}

Supprimer un endpoint

Définitif. Pour arrêter les livraisons sans perdre l'endpoint et son secret, préférez PATCH avec is_active: false.

Paramètres

Nom	Emplacement	Requis	Description
id	path	oui	Le numéro de l'endpoint, tel que rendu par GET /v1/webhooks.

Réponses

• 204 — Supprimé
• 401 — Clé API manquante ou rejetée (Error)
• 403 — La clé ne porte pas le scope can_manage_webhooks (Error)
• 404 — Aucun endpoint de ce numéro pour ce compte (Error)
• 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

GET /v1/webhooks/{id}/secret

Relire le secret de signature

ⓘ OUI, CELUI-CI SE RELIT, contrairement au secret d'une clé API. La différence n'est pas une inconséquence : la plateforme doit détenir le secret du webhook pour SIGNER, il est donc stocké de façon récupérable. Une clé API n'est stockée qu'en empreinte, et ne peut donc pas être relue.

Paramètres

Nom	Emplacement	Requis	Description
id	path	oui	Le numéro de l'endpoint, tel que rendu par GET /v1/webhooks.

Réponses

• 200 — OK (WebhookSecret)
• 401 — Clé API manquante ou rejetée (Error)
• 403 — La clé ne porte pas le scope can_manage_webhooks (Error)
• 404 — Aucun endpoint de ce numéro pour ce compte (Error)
• 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

Schémas

Les formes renvoyées par les opérations ci-dessus.

WebhookList

Champ	Type	Description
data	Webhook[]
data[].id	integer
data[].url	string
data[].description	string
data[].subscribed_events	string[]
data[].is_active	boolean
data[].created_at	string
data[].total_sent	integer
data[].total_success	integer
data[].total_failed	integer
data[].consecutive_failures	integer	Vingt échecs consécutifs suspendent l'endpoint une heure ; un seul succès le réhabilite.
data[].last_success_at	string
data[].last_failure_at	string

Error

Champ	Type	Description
error	object
error.code	string
error.message	string

WebhookCreated

Champ	Type	Description
data	object
data.webhook	Webhook	Un endpoint de notification, avec les compteurs de livraison que la plateforme tient.
data.webhook.id	integer
data.webhook.url	string
data.webhook.description	string
data.webhook.subscribed_events	string[]
data.webhook.is_active	boolean
data.webhook.created_at	string
data.webhook.total_sent	integer
data.webhook.total_success	integer
data.webhook.total_failed	integer
data.webhook.consecutive_failures	integer	Vingt échecs consécutifs suspendent l'endpoint une heure ; un seul succès le réhabilite.
data.webhook.last_success_at	string
data.webhook.last_failure_at	string
data.secret	string	Le secret de signature. Il n'apparaît qu'ici et sur GET /v1/webhooks/{id}/secret.
data.created	boolean	false quand l'endpoint existait déjà pour cette URL.

WebhookSecret

Champ	Type	Description
data	object
data.id	integer
data.url	string
data.secret	string