Endpoints de webhook
Enregistrez et gérez les URL auxquelles Wajub envoie des notifications d'événements signées.
Un endpoint de webhook est une URL que vous enregistrez pour recevoir, en temps réel, des notifications signées pour les types d'événements auxquels vous vous abonnez. Consultez Webhooks pour le guide de mise en place complet.
Clé privée requise
Gérer les endpoints de webhook exige la clé privée (sk.). L'URL d'un endpoint live doit
utiliser https://, sinon l'appel répond 422 ; un endpoint sandbox accepte aussi http://.
Endpoints
Le chemin est /webhooks
Cette ressource est exposée sous /webhooks, et non /webhook-endpoints : webhook-endpoints
désigne ici le concept produit (l'URL enregistrée et sa configuration), et non les événements
qu'elle reçoit (voir le catalogue des événements).
| Méthode | Chemin | Description |
|---|---|---|
POST | /webhooks | Créer un endpoint de webhook |
GET | /webhooks | Lister les endpoints de webhook |
GET | /webhooks/{id} | Récupérer un endpoint de webhook |
PUT | /webhooks/{id} | Modifier un endpoint de webhook |
DELETE | /webhooks/{id} | Supprimer un endpoint de webhook |
POST | /webhooks/{id}/rotate-secret | Faire tourner le secret de signature |
Les règles qu'un endpoint doit respecter
Chaque règle non respectée renvoie un 422 qui nomme le champ.
| Règle | Refusé avec |
|---|---|
L'URL d'un endpoint live utilise https://. Un endpoint sandbox peut utiliser http:// | A live webhook endpoint must use an https:// URL. |
L'URL se résout en une adresse internet publique : les adresses privées et internes sont refusées. Pour un test local, utilisez wajub listen | The url must not point to a private or internal IP address., ou must not resolve to a private IP address pour un nom d'hôte |
| Un seul endpoint par URL dans chaque environnement, à la création et quand une URL change | A webhook endpoint with this URL already exists. |
Au moins un type d'événement, à la création et sur PUT. ["*"] prend tous les types ; une liste vide est refusée | The events field must have at least 1 items. |
| Une URL de 2048 caractères au plus, un type de 100, une description de 500 | Le message de longueur propre au champ |
À partir de la version 2026-10-12 de l'API, chaque type est l'un du catalogue des événements, ou *. Un type qui n'existe pas, comme payment.refunded, un type mal orthographié ou un préfixe comme payment.* est refusé, sur events.N | payment.refunded is not an event type an endpoint receives. Use a type from the event catalog, or *. |
Sur les versions antérieures, les noms de types d'événements ne sont pas vérifiés : un nom mal orthographié est enregistré et ne correspond jamais à rien. Copiez-les depuis le catalogue des événements.
PUT /webhooks/{id} avec "active": false désactive l'endpoint sans le supprimer : plus rien ne
lui est livré, nouvelles tentatives en attente comprises.
"active": true le réactive ; les événements enregistrés entre-temps ne sont pas envoyés, et vous
pouvez les rejouer avec POST /events/{id}/resend.
Événements
| Événement | Déclencheur |
|---|---|
webhook_endpoint.created | Endpoint enregistré |
webhook_endpoint.updated | Endpoint modifié |
webhook_endpoint.deleted | Endpoint supprimé |