Vérification de la signature d’un webhook

Définition

La vérification de la signature d’un webhook est un mécanisme qui permet d’authentifier la source d’un événement de webhook. Lorsqu’un fournisseur comme Resend ou SendGrid envoie une notification concernant un événement e-mail, il inclut un hash de la charge utile signé avec une clé secrète. Le serveur destinataire utilise la même clé secrète pour recalculer le hash et le comparer à la signature fournie dans l’en-tête de la requête.

Fonctionnement pas à pas

Le fournisseur génère un hash HMAC à partir d’un secret partagé et du corps de la requête. Ce hash est envoyé dans un en-tête, souvent nommé X-Signature ou similaire. Le destinataire récupère le corps brut de la requête et l’en-tête de signature, puis calcule son propre hash HMAC avec le secret partagé. Si le hash calculé correspond à la valeur de l’en-tête, la requête est authentique. S’ils diffèrent, la requête est rejetée comme non autorisée.

Pourquoi c’est important pour les expéditeurs

Sans vérification, quiconque connaît l’URL de votre webhook peut envoyer de fausses données à votre serveur. Cela peut entraîner des mises à jour erronées de la base de données, par exemple marquer comme bounce un e-mail qui a bien été délivré. La vérification empêche les attaques par usurpation et garantit que votre application ne réagit qu’aux événements légitimes déclenchés par votre infrastructure e-mail.

Notes opérationnelles

Une erreur courante consiste à convertir le corps de la requête en objet JSON avant de vérifier la signature. Comme les parseurs JSON peuvent modifier les espaces ou l’ordre des clés, la chaîne obtenue peut ne plus correspondre à la charge utile d’origine utilisée par le fournisseur. Utilisez toujours le corps brut, non analysé, de la requête pour les calculs HMAC afin d’éviter les échecs de vérification.

Exemple de mise en œuvre

Dans un environnement Node.js, un développeur utilise le module crypto pour créer un hash hmac sha256 du corps brut à l’aide du secret du fournisseur. Le résultat est ensuite comparé à l’en-tête de signature avec une fonction de comparaison à temps constant pour empêcher les attaques temporelles. SendHQ propose des outils gratuits sur https://sendhq.cc/tools pour vous aider à gérer les différentes configurations e-mail qui précèdent souvent la mise en place d’un webhook.

Les questions que posent les équipes

Sources primaires

• Documentation Resend — Resend
• Documentation développeur Postmark — Postmark
• Documentation SendGrid — Twilio SendGrid