Tester les webhooks
Trois niveaux, du test unitaire jusqu'à la relance d'une livraison live.
Un handler de webhook possède trois modes d'échec à tester séparément : il accepte un élément qu'il devrait refuser, refuse un élément qu'il devrait accepter ou effectue deux fois le même travail. Chacun est détecté à un niveau différent.
| Niveau | Problème détecté | Prérequis |
|---|---|---|
| Test unitaire | Un vérificateur qui accepte une signature falsifiée | Aucun, il s'agit d'un calcul pur |
| La CLI | Un handler qui plante sur un véritable payload | wajub listen et wajub trigger |
| Konsole | Un endpoint réellement inaccessible depuis votre serveur | Un endpoint enregistré |
Niveau 1 : signer vous-même un payload
La signature utilise HMAC-SHA256 sur "{timestamp}.{body}". Un test peut donc en produire une valide sans aucun accès réseau. Écrivez les quatre cas : signature valide, mauvais secret, corps altéré et ancien horodatage.
# The string that gets signed, for reference
TIMESTAMP=1748083260
BODY='{"id":"evt_test_1","event":"payment.succeeded","data":{}}'
printf '%s.%s' "$TIMESTAMP" "$BODY" \
| openssl dgst -sha256 -hmac "whsec_test_secret" -r \
| cut -d' ' -f1Signez aussi les octets bruts dans le test
Si votre test sérialise à nouveau l'objet avant de le signer, il teste un corps différent de celui qu'il envoie et réussit pour une mauvaise raison. Construisez la chaîne du corps une seule fois, signez-la, puis envoyez-la.
Niveau 2 : un événement réel sur votre machine
Les tests unitaires vérifient le vérificateur. Ils ne prouvent pas que le handler résiste à un véritable payload, avec des champs inattendus et des types que vous n'aviez pas prévus.
# 1
wajub listen --forward-to localhost:3000/webhooks/wajub
# 2
wajub trigger payment.succeeded
wajub trigger payment.failed
wajub trigger refund.succeededLa CLI signe les éléments qu'elle transfère avec un secret qu'elle affiche. Votre vérification s'exécute donc réellement. Exportez ce secret. Rien d'autre ne change dans votre code.
Le déclenchement de payment.succeeded livre à lui seul cinq événements. Si votre handler n'en connaît qu'un, les quatre autres arrivent actuellement dans sa branche par défaut.
Niveau 3 : l'endpoint déployé
Deux boutons distincts dans Konsole répondent à deux questions différentes.
| Bouton | Vérification effectuée |
|---|---|
| Send test | Wajub peut atteindre votre URL et la vérification de signature réussit |
| Retry a delivery | Votre handler traite maintenant un véritable événement qui avait auparavant échoué |
Send test ne prouve pas le bon fonctionnement de votre handler
Son payload contient le type dans type, pas dans event, et ne contient ni api_version, ni pending_webhooks, ni request. Un handler développé à partir de ce payload échoue en production. Utilisez-le pour tester la connectivité et utilisez wajub trigger pour tester le comportement.
Les quatre vérifications utiles
Ces quatre vérifications s'exécutent au niveau 1, dans votre propre suite et sans réseau. Chacune précise l'entrée qui produit la condition. Aucune ne nécessite donc une livraison réelle pour reproduire le résultat.
| Vérification | Méthode | Condition de réussite |
|---|---|---|
| Une signature falsifiée est rejetée | Un mauvais secret, un octet modifié dans le corps ou l'absence complète de X-Wajub-Signature | Votre endpoint répond avec un code 4xx et n'écrit rien |
| Une livraison rejouée est rejetée | Une signature valide sur un horodatage vieux de 400 secondes | Votre endpoint répond avec un code 4xx, car la fenêtre complète est de 300 secondes |
| Deux livraisons du même événement n'effectuent le travail qu'une fois | Le même corps et les mêmes en-têtes, envoyés une deuxième fois | Une commande, un e-mail et un crédit |
| Un handler occupé répond toujours à temps | Votre handler alors que la file d'attente est déjà pleine | La réponse part en moins de 10 secondes, car une réponse plus lente déclenche une nouvelle tentative |
La première est votre seule protection entre le code de livraison de vos commandes et toute personne qui découvre votre URL. L'absence de la troisième vous coûte de l'argent, car chaque livraison est tentée jusqu'à cinq fois.
Pages associées