Webhooks

Les endpoints, chaque tentative de livraison et la manière d'en relancer une.

La vue Webhooks comporte trois onglets : les events produits par votre compte, les deliveries effectuées à partir de ces événements et les endpoints auxquels ils ont été envoyés. Les événements disposent de leur propre page. Celle-ci traite des deux autres onglets.

Webhook deliveries

last hour

Method	Endpoint	Status	Duration	Attempt
POST	/webhooks/wajub	500	10021 ms	1 of 5
POST	/webhooks/wajub	500	240 ms	2 of 5
POST	/webhooks/wajub	200	142 ms	3 of 5

Livraisons

Une ligne correspond à une tentative, pas à un événement. Une livraison relancée trois fois produit trois lignes qui partagent le même identifiant de livraison.

Colonne	Remarque
Statut	`success`, `retrying` ou `failed`
Code de réponse	La réponse de votre endpoint, vide en cas d'erreur réseau
Durée	Le temps de réponse de votre endpoint. Une ligne à 10 000 ms correspond à un délai dépassé
Tentative	De 1 à 5
Endpoint	L'URL concernée, lorsque vous en avez plusieurs

Filtres : recherche dans l'événement, statut, endpoint et plage de dates en journées entières. Cinquante résultats par page.

Le panneau de détail contient le payload envoyé et le corps renvoyé par votre endpoint. Vous pouvez ainsi découvrir que votre erreur 500 contient une stack trace lisible directement ici.

Relancer des livraisons

Deux méthodes sont proposées. Toutes deux sont décomptées du quota mensuel max_webhooks de votre plan.

Action	Portée
Retry	Une livraison
Bulk retry	Jusqu'à 100 livraisons échouées en une fois, sur une période et éventuellement pour un seul endpoint

Bulk retry sélectionne uniquement les livraisons dont le statut est failed, dans la période choisie, qui couvre par défaut les dernières 24 heures. Chaque livraison du lot consomme une unité du quota. Le lot s'arrête lorsque le quota est épuisé.

Corrigez l'endpoint avant de relancer les livraisons

Une relance renvoie le même payload vers la même URL. Si le handler produit encore une exception, vous consommez votre quota pour reproduire l'échec. Déployez la correction, relancez une livraison, vérifiez sa réussite, puis relancez les autres en lot.

Endpoints

La création d'un endpoint exige une URL et une liste de types d'événement.

Champ	Règle
URL	Une URL valide, limitée à 2 048 caractères et qui ne pointe pas vers une adresse privée ou interne
Événements	Au moins un type parmi ceux proposés par Konsole
Description	Du texte libre, utile lorsque vous avez plusieurs endpoints

Konsole vérifie le nom des événements, contrairement à l'API

Le sélecteur propose uniquement des types valides et refuse les autres. POST /webhooks accepte tout tableau non vide. Une faute de frappe transmise par l'API est donc enregistrée sans jamais produire de correspondance. Consultez le catalogue des événements.

Les adresses privées et internes sont volontairement refusées. Un endpoint qui pointe vers localhost ou vers une plage privée transformerait le worker de livraison de Wajub en sonde du réseau interne. Pour le développement local, utilisez wajub listen.

Le secret

Chaque endpoint possède son propre secret de signature, affiché une seule fois lors de sa création. Ensuite, Reveal secret l'affiche à nouveau après confirmation de votre mot de passe. Cette action est enregistrée.

Le renouvellement se fait depuis l'API avec POST /webhooks/{id}/rotate-secret. Déployez le nouveau secret avant de le renouveler. Dans le cas contraire, les livraisons effectuées entre le renouvellement et votre déploiement échoueront lors de la vérification de signature.

Passer un endpoint de sandbox en live

Vous pouvez copier un endpoint de sandbox en mode live en une seule action. Son URL et sa liste d'événements sont conservées, mais il reçoit un nouveau secret, car le secret de sandbox a été présent sur les machines des développeurs.

Mettez à jour la variable d'environnement live après la copie

Le secret de l'endpoint live diffère de celui de la sandbox. Un serveur qui conserve l'ancienne valeur rejettera chaque livraison live avec une erreur de signature.

Le test de connectivité n'est pas un événement réel

Send test envoie à l'endpoint un payload fixe signé avec son véritable secret. Il prouve que l'URL est accessible et que votre vérification de signature réussit. Il ne prouve pas le bon fonctionnement de votre handler, car le payload possède une structure différente de celle d'une livraison réelle.

Le contenu réellement envoyé par Send test

{

"id": "evt_test_kZ3qP8mWvL2xR7tB5nY4hC6d",

"type": "webhook.test",

"created": "2026-01-15T10:30:00+00:00",

"data": {

"id": "test_123",

"message": "This is a test webhook from Wajub."

"livemode": false

}

Une livraison réelle présente quatre différences, dont chacune a déjà causé des problèmes.

Livraison réelle	Send test
Le type se trouve dans `event`	Le type se trouve dans `type`
Contient `api_version`, `pending_webhooks`, `request`	Ne contient aucun de ces champs
Envoie `X-Wajub-Delivery-Id`	Ne l'envoie pas
Enregistrée avec le statut `success`	Enregistrée avec le statut `delivered`

Ne développez pas votre handler à partir du payload de test

Un handler qui lit payload.type fonctionne avec Send test, mais ne se déclenche jamais en production, où le champ est event. Utilisez ce bouton pour tester la signature. Testez le handler avec wajub trigger, qui produit de vrais événements.

Pages associées