Un secret de signature de webhook est un identifiant, pas un simple détail de configuration. Envoyez-le comme un mot de passe : vérifiez qui le reçoit, transmettez-le par un canal qui n’en garde aucune copie et assurez-vous qu’il finit dans un gestionnaire de secrets plutôt que dans un ticket. En bref : un lien secret à usage unique envoyé à un contact vérifié, et les instructions de configuration envoyées à part.
La suite de ce guide traite du choix du canal, des vérifications avant l’envoi, de ce que le client doit faire de la valeur, puis du renouvellement et du dépannage, sans jamais recoller le secret.
Quel canal doit transporter le secret ?
Choisissez le canal en vous posant deux questions : pouvez-vous vérifier qui est en mesure de l’ouvrir, et combien de copies laisse-t-il derrière lui ? L’e-mail et la messagerie échouent à la seconde, car chaque message est conservé, synchronisé et exporté bien après la fin de la transmission.
| Méthode | Ce qu’elle apporte | À vérifier avant l’envoi |
|---|---|---|
| Portail client authentifié | Accès nominatif que vous pouvez révoquer | Le compte appartient au bon contact |
| Lien secret à usage unique | Détruit après une ouverture, rien ne reste dans le message | L’adresse à laquelle vous l’envoyez, vérifiée séparément |
| Messagerie chiffrée | Protection pendant le transit | Qui d’autre peut ouvrir cette conversation |
Un portail client avec des comptes individuels est un bon premier choix quand il existe. Donnez l’accès à une personne nommée, pas à un fil de projet partagé, et retirez-le une fois la transmission terminée.
Un lien à usage unique tient l’identifiant à l’écart de l’e-mail ou du message qui sert à vous coordonner. Avec LinkPilot, le secret est chiffré dans votre navigateur avant d’être stocké, la copie stockée est détruite après une ouverture, et vous pouvez régler l’expiration du lien sur une heure, un jour ou une semaine. Les forfaits Pro ajoutent une phrase de passe, que vous communiquez par un autre canal. Ces contrôles encadrent la transmission. Ils ne remplacent pas la vérification de la personne à l’autre bout.
La messagerie chiffrée est la solution de repli quand aucune des deux options précédentes n’est praticable. Le chiffrement en transit ne corrige ni un message mal adressé ni un groupe trop large, donc la vérification du destinataire compte encore plus.
Quel que soit votre choix, réservez l’e-mail et la messagerie en clair à la coordination. Même les services qui chiffrent en transit gardent hors de votre contrôle la conservation, les sauvegardes et l’accès aux comptes.
Vérifier le client et le destinataire
Un canal sécurisé ne sert à rien si le secret arrive dans la mauvaise boîte. Avant l’envoi, confirmez que la personne qui le demande est responsable de l’intégration et que le canal prévu lui appartient vraiment.
- Confirmez l’identité à partir d’une source connue. Utilisez une fiche de contact fiable, une relation commerciale existante ou la procédure habituelle du client. Un nouveau demandeur, un changement soudain d’interlocuteur ou une urgence inhabituelle justifient une vérification indépendante.
- Lisez l’adresse caractère par caractère, surtout si vous la copiez depuis un ticket ou un message récent. C’est avec les noms qui se ressemblent et les boîtes partagées que les erreurs arrivent.
- Regardez qui d’autre a accès. Avant de partager par un portail ou un espace de travail, consultez la liste des membres et retirez ceux qui n’ont pas besoin de l’identifiant.
- Confirmez la réception par un second canal. Si le lien est parti par e-mail, demandez sur un numéro de téléphone connu ou sur le canal habituel du projet si l’accès a fonctionné. N’incluez pas le secret dans ce message.
Partagez le secret avec la seule personne qui configurera l’endpoint, et laissez-la le placer dans le gestionnaire de secrets du client. Si plusieurs ingénieurs en ont besoin, ce sont les contrôles d’accès de ce gestionnaire qui doivent régler qui le voit, pas des copies distinctes envoyées à chacun.
Préparer le secret avant la transmission
Décidez à quoi l’identifiant est rattaché, où le client doit le conserver et combien de temps la transmission reste ouverte. Cette préparation rend le renouvellement et le dépannage bien plus simples par la suite.
- Un secret par client ou par endpoint. Avec un secret réutilisé, une seule fuite touche toutes les intégrations qui partagent la valeur, et le renouveler pour un client les perturbe toutes. Notez en interne à quel endpoint appartient chaque secret, sans recopier la valeur dans les notes de projet.
- Stockez votre propre copie dans un gestionnaire de secrets. Pas dans un fichier texte local, un ticket ou un document partagé. La même discipline s’applique au partage de clés API : limitez qui peut atteindre l’identifiant et gardez la transmission brève.
- Fixez une fenêtre de récupération. Laissez au client le temps de récupérer la valeur et de terminer la configuration, pas plus. Un lien qui se détruit après une ouverture et expire au bout d’un jour suffit pour la plupart des transmissions ; si la fenêtre est passée, créez-en un nouveau au lieu de rouvrir l’ancien.
- Envoyez les instructions de configuration à part. L’URL de l’endpoint, l’en-tête de signature et les étapes de vérification ont leur place dans la documentation du client ou sur le canal du projet. Tant qu’elles restent séparées du secret, copier la page d’instructions ne revient pas à copier l’identifiant.
Aider le client à le stocker et à l’utiliser en toute sécurité
La transmission n’est pas terminée quand le client peut lire la valeur. Elle l’est quand le serveur peut la lire de manière sécurisée et s’en sert pour vérifier les signatures entrantes.
- Stockez-le dans un gestionnaire de secrets ou une variable d’environnement protégée que le processus serveur peut lire, avec un accès limité à l’application et aux personnes qui l’exploitent.
- Tenez-le à l’écart du code source, des logs et des charges utiles des webhooks. Le secret sert à calculer ou à vérifier une signature. Il ne circule jamais dans le corps de la requête et ne doit apparaître ni dans la sortie de débogage, ni dans les dépôts, ni dans les tickets de support. Vérifiez ce que capturent vos outils de déploiement avant d’activer des diagnostics détaillés.
- Vérifiez les signatures sur le serveur. Le destinataire recalcule la signature sur le corps brut de la requête avec le secret partagé et la compare à l’en-tête défini par l’expéditeur. La signature prouve que la requête est authentique et non modifiée ; elle ne chiffre pas la charge utile. Le guide de HackerOne sur la signature des webhooks explique pourquoi le corps brut et le bon secret comptent tous les deux.
- Lancez un événement de test. Demandez au client de confirmer qu’une signature valide est acceptée et qu’une signature volontairement faussée est rejetée. Cela détecte les erreurs habituelles : le secret d’un autre endpoint, ou un corps analysé avant la vérification. Séparez les identifiants de test et de production lorsque l’intégration le permet.
Réduire le risque après la transmission
La transmission doit laisser une trace exploitable, pas une série de copies en trop.
- Notez qui a été autorisé et quand. Consignez le destinataire, l’endpoint ou le client, et l’heure de la transmission. Jamais la valeur. Si vous ne pouvez pas savoir si un lien a été ouvert ou qui pouvait atteindre un dossier partagé, considérez-le comme une raison de resserrer la procédure la prochaine fois.
- Renouvelez le secret au moindre soupçon de fuite. Un secret collé dans un ticket, envoyé à la mauvaise adresse ou retrouvé dans un log n’est plus privé. Générez-en un nouveau, mettez à jour l’endpoint et invalidez l’ancienne valeur. Supprimer un lien de partage n’annule pas une fuite ; seul le renouvellement le fait.
- Convenez dès maintenant de la procédure de renouvellement. Décidez qui demande, crée et installe le remplaçant, si l’implémentation accepte un court chevauchement et comment vous testerez la nouvelle valeur avant de retirer l’ancienne. Une procédure connue vaut mieux qu’un échange précipité pendant une panne.
- Faites le ménage. Une fois la récupération confirmée par le client, révoquez les accès temporaires et supprimez les copies égarées dans les brouillons, les tickets et les notes. Vérifiez les règles de conservation de chaque système concerné : supprimer un message d’une vue l’efface rarement des sauvegardes.
Dépanner sans exposer le secret
Un problème de transmission ne justifie pas de renvoyer l’identifiant par un canal moins sûr. Déterminez d’abord lequel de ces trois cas se présente : le client ne peut pas récupérer le secret, ne peut pas configurer l’endpoint, ou reçoit les requêtes mais ne peut pas valider les signatures.
- La récupération a échoué ou la fenêtre a expiré. Vérifiez de nouveau le destinataire et organisez une nouvelle transmission contrôlée. Ne collez pas la valeur dans un ticket et ne demandez pas au client de vous renvoyer la sienne pour comparaison.
- Signature non concordante. C’est presque toujours un problème de données d’entrée de la vérification : le mauvais secret pour cet endpoint, un corps reformaté avant le calcul du hash ou un en-tête mal lu. Demandez au client de tester avec un événement connu au moyen des outils de test de l’expéditeur.
- Les requêtes n’arrivent jamais. C’est un problème de livraison ou de routage, pas d’identifiant. Vérifiez les horodatages, les codes de réponse et le choix de l’endpoint avant d’envisager un renouvellement. La documentation sur les webhooks de Stripe est un bon modèle pour distinguer l’enregistrement de l’endpoint et la livraison des événements de la vérification de signature.
- Partagez des diagnostics expurgés. L’ID de l’événement, l’horodatage, l’endpoint et la catégorie d’erreur suffisent. Retirez le secret, la signature complète lorsqu’elle est sensible et les champs privés de la charge utile, puis contrôlez l’expurgation avant d’envoyer un exemple de requête.
Vérifiez le destinataire, transmettez le secret une seule fois par un canal qui l’oublie, assurez-vous qu’il arrive dans un gestionnaire de secrets et renouvelez-le sans hésiter s’il a pu fuiter. Pour l’usage plus large des liens à usage unique dans le travail des équipes techniques, consultez le partage de liens sécurisés pour les développeurs.