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.
Le secret
Section titled “Le secret”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.
Vérifier un appel
Section titled “Vérifier un appel”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-timestamptrop 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.
Relances
Section titled “Relances”| 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.
Adresses refusées
Section titled “Adresses refusées”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.
Alerte et sécurité
Section titled “Alerte et sécurité”- 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.