Skip to content

Vérifier la signature

Tout appel porte une signature Standard Webhooks : un HMAC-SHA256 de webhook-id.webhook-timestamp.corps, calculé avec le secret du webhook.

Il s’affiche une seule fois, à la création du webhook ou quand on le régénère. Il commence par whsec_ ; le préfixe se retire et le reste se décode du base64 pour donner la clé du HMAC.

import { createHmac, timingSafeEqual } from "node:crypto";
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
function verify(headers, rawBody, secret) {
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const signed = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${rawBody}`;
const expected = `v1,${createHmac("sha256", key).update(signed).digest("base64")}`;
const given = headers["webhook-signature"];
return (
typeof given === "string" &&
given.length === expected.length &&
timingSafeEqual(Buffer.from(expected), Buffer.from(given))
);
}

Trois règles qui évitent les faux négatifs :

  • Comparez sur le corps brut, avant de le décoder en JSON : le moindre espace reformaté change la signature.
  • Comparez en temps constant (timingSafeEqual) plutôt qu’avec ===.
  • Refusez un webhook-timestamp trop vieux (quelques minutes) : une signature valide reste valide, c’est l’âge de l’appel qui protège du rejeu.

Dans n8n, le corps brut arrive dans le nœud webhook ; si le jeton ne suffit pas, la vérification se fait dans un nœud Code avec la fonction ci-dessus.

Réponse de votre adresse Ce que fait Kalepin
2xx Envoi réussi, contenu effacé
Autre code, ou délai de 10 s dépassé L’envoi repart après 1 min, 5 min, 30 min, 2 h puis 6 h ; echec après la sixième tentative
Redirection (3xx) Suivie nulle part : c’est un échec

Le webhook-id ne change pas d’une relance à l’autre : c’est à votre récepteur d’écarter le doublon s’il en reçoit un. Le contrôle de Kalepin ne lit jamais la réponse : seul le statut compte.

Une adresse doit être https et publique. Sont refusés, en IPv4 comme en IPv6 : http, localhost et tout ce qui n’est pas sur l’internet public — adresses privées, loopback, link-local (dont les métadonnées cloud), CGNAT, multicast, réservées, et les IPv6 qui portent une IPv4. Un nom est vérifié au moment de la connexion, ce qui empêche un nom de répondre une adresse publique au contrôle puis une adresse privée à l’appel.

  • Ajouter un webhook, ou changer son adresse, déclenche une notification système sur vos postes pendant 7 jours : elle nomme l’hôte où partent vos notes et dit de supprimer le webhook si ce n’est pas vous. Aucun réglage ne la coupe.
  • Les secrets sont scellés avec la clé du serveur. Sans elle, les webhooks sont désactivés (409 no_secret_key).
  • Les webhooks sont réservés aux offres Pilote, Pro et Business. En Free, la création et le test répondent 403 plan_required, et les webhooks existants se mettent en pause sans être supprimés.