curl -X POST /wp-json/monplugin/v1/docusign-webhook -d @fixtures/envelope-completed.json — c’est cette commande, rejouée automatiquement à chaque exécution de la suite, qui garantit que le traitement d’un webhook Docusign reste correct après chaque modification du code. Pas une supposition, un rejeu littéral d’un événement réel.
Un webhook Docusign notifie qu’une enveloppe de signature a changé de statut : envoyée, consultée, signée, ou refusée. Le plugin qui reçoit cette notification doit mettre à jour un enregistrement WordPress en conséquence, sans jamais faire confiance aveuglément au contenu reçu.
Capturer une charge utile réelle comme fixture
Plutôt que d’inventer un JSON de webhook à la main, le point de départ a été une véritable notification reçue en environnement de recette Docusign, anonymisée ensuite : noms remplacés, adresses email neutralisées, identifiants d’enveloppe randomisés mais au format valide.
{
"event": "envelope-completed",
"envelopeId": "11111111-2222-3333-4444-555555555555",
"status": "completed",
"recipients": [
{ "email": "signataire@exemple.test", "status": "completed" }
]
}
Cette fixture reflète fidèlement la structure réelle, y compris des champs superflus que Docusign ajoute parfois sans documentation précise. Un JSON simplifié à la main aurait masqué ces détails et laissé passer un bug de parsing.
Vérifier la signature avant tout traitement métier
Docusign signe chaque webhook avec une clé HMAC partagée, transmise dans l’en-tête X-DocuSign-Signature-1. Le premier test de la suite vérifie qu’une requête sans signature valide est rejetée avec un code 401, avant même que le corps ne soit interprété.
public function test_signature_invalide_est_rejetee() {
$request = new WP_REST_Request( 'POST', '/monplugin/v1/docusign-webhook' );
$request->set_header( 'X-DocuSign-Signature-1', 'signature-invalide' );
$request->set_body( file_get_contents( __DIR__ . '/fixtures/envelope-completed.json' ) );
$response = rest_do_request( $request );
$this->assertSame( 401, $response->get_status() );
}
Un deuxième test, symétrique, vérifie qu’une signature correctement calculée avec la clé de test laisse passer la requête jusqu’au traitement métier.
Garantir l’idempotence du traitement
Docusign documente explicitement qu’un même événement peut être envoyé plusieurs fois en cas de non-réponse rapide du serveur cible. Le plugin doit donc traiter deux fois le même envelopeId sans créer deux enregistrements ni envoyer deux emails de confirmation.
- Un identifiant d’enveloppe unique en base, contrainte au niveau du schéma
- Un test qui envoie deux fois la même fixture et vérifie une seule ligne créée
- Un test qui vérifie qu’aucun email n’est envoyé lors du deuxième envoi
Simuler les statuts intermédiaires
Trois autres fixtures couvrent les statuts sent, delivered et declined. Chacune vérifie une transition précise dans la table de suivi interne, avec une matrice qui interdit certaines transitions impossibles, comme passer de declined à completed sans nouvel envoi d’enveloppe.
Un webhook n’est fiable que si le code qui le reçoit part du principe qu’il peut mentir, se répéter, ou arriver dans le désordre.
Ce que la suite ne couvre pas
L’envoi initial de la demande de signature vers Docusign, avec la construction de l’enveloppe et l’appel à l’API sortante, relève d’un test distinct qui mocke le client HTTP Docusign. Mélanger les deux directions — envoi et réception — dans la même suite aurait rendu chaque échec plus difficile à interpréter.
En résumé
La fixture réelle anonymisée, la vérification stricte de la signature, et le test explicite d’idempotence forment un triptyque simple à reproduire pour n’importe quel webhook tiers. Le coût de mise en place a été d’une journée ; il a évité un incident de double facturation trois mois plus tard, lorsque Docusign a effectivement renvoyé deux fois la même notification suite à un pic de latence réseau.
