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
• 401 — Clé API manquante ou rejetée
• 403 — La clé ne porte pas le scope can_manage_webhooks
• 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After

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.*.

Réponses

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

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
• 401 — Clé API manquante ou rejetée
• 403 — La clé ne porte pas le scope can_manage_webhooks
• 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After

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

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.

Réponses

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

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
• 403 — La clé ne porte pas le scope can_manage_webhooks
• 404 — Aucun endpoint de ce numéro pour ce compte
• 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After

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