Chaque requête webhook est signée avec le secret de signature de votre point de terminaison. Vérifiez la signature avant d'autoriser une requête afin que votre serveur ne traite que les événements provenant réellement de Notiondesk et n'ayant pas été modifiés lors de leur transmission.
tv1X-ND-Signature{t}.{raw body}v1Avant de commencer
- Vous disposez du secret de signature que vous avez copié lors de l'ajout du point de terminaison. Il commence par
nd_whsec_. Si vous l'avez perdu, veuillez le renouveler. Consultez la section « Renouveler le secret de signature » .
- Votre récepteur peut lire le corps de la requête exactement tel qu'il est arrivé, avant toute analyse JSON.
Comment fonctionne la signature
Chaque requête comporte un en-tête X-ND-Signature :
X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb| Partie | Qu'est-ce que c'est |
|---|---|
t | Date d'envoi de la requête, en secondes depuis le 1er janvier 1970 (UTC). Chaque nouvelle tentative se voit attribuer une nouvelle valeur t. |
v1 | Le HMAC SHA-256 de t, un point et le corps brut de la requête, signé avec votre secret de signature et écrit en hexadécimal minuscule |
Vérifier une demande
- Lisez le corps brut de la requête sous forme d'octets. Ne l'analysez pas au préalable.
- Divisez l'en-tête
X-ND-Signatureen virgules et liseztetv1.
- Constituez le texte signé :
t, un point, puis le corps brut. Par exemple :1794955939.{"id":"019a8f2e-...",...}.
- Calculez un HMAC SHA-256 de ce texte avec votre secret de signature complet, y compris
nd_whsec_, et écrivez-le en hexadécimal minuscule.
- Comparez votre résultat avec
v1en utilisant une comparaison à temps constant.
- Vérifiez que
tcorrespond à l'heure de votre serveur dans les 5 minutes qui s'y rattachent.
- En cas d'échec d'une vérification, répondre
400et ignorer la requête. En cas de réussite, répondre200et traiter l'événement.
Exemple Node.js
Cela fonctionne avec Node.js 18 ou version ultérieure et Express. express.raw conserve le corps sous forme d'octets bruts, ce dont la signature a besoin.
Exemple Python
Cela fonctionne avec Python 3.9 ou version ultérieure et Flask. request.get_data() renvoie le corps brut.
Faites tourner le secret de la signature
Changez le secret s'il a pu fuiter ou si vous l'avez perdu.
const crypto = require('crypto');
const express = require('express');
function verifyNotiondeskSignature(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(
String(header ?? '').split(',').map((part) => part.trim().split('=')),
);
if (!/^\d+$/.test(parts.t ?? '') || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.`)
.update(rawBody)
.digest('hex');
const received = Buffer.from(parts.v1);
const computed = Buffer.from(expected);
return received.length === computed.length && crypto.timingSafeEqual(received, computed);
}
const app = express();
app.post('/webhooks/notiondesk', express.raw({ type: 'application/json' }), (req, res) => {
const valid = verifyNotiondeskSignature(
req.body,
req.get('X-ND-Signature'),
process.env.NOTIONDESK_WEBHOOK_SECRET,
);
if (!valid) return res.sendStatus(400);
res.sendStatus(200);
const event = JSON.parse(req.body);
console.log('Received', event.event, event.id);
});
app.listen(3000);import hashlib
import hmac
import os
import time
from flask import Flask, request
app = Flask(__name__)
def verify_notiondesk_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
try:
parts = dict(part.strip().split("=", 1) for part in header.split(","))
timestamp = int(parts["t"])
received = parts["v1"]
except (AttributeError, KeyError, ValueError):
return False
if abs(time.time() - timestamp) > tolerance:
return False
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received)
@app.post("/webhooks/notiondesk")
def notiondesk_webhook():
valid = verify_notiondesk_signature(
request.get_data(),
request.headers.get("X-ND-Signature", ""),
os.environ["NOTIONDESK_WEBHOOK_SECRET"],
)
if not valid:
return "", 400
event = request.get_json()
print("Received", event["event"], event["id"])
return "", 200- Ouvrez le point de terminaison dans Paramètres > Développeurs > Webhooks .
- Sous « Secret de signature » , cliquez sur « Rotation » , puis à nouveau sur « Rotation » pour confirmer.
- Copiez le nouveau secret, stockez-le sur votre serveur, puis cliquez sur « Je l'ai enregistré » .
Si quelques requêtes échouent pendant le changement, elles sont retentées après 1 minute avec le nouveau secret.
Erreurs courantes
- Vérifiez le JSON analysé plutôt que le corps brut. L'analyse du corps et sa reconversion en texte modifient l'espacement et l'échappement des caractères, ce qui rend la signature incorrecte. Vérifiez les octets reçus, puis analysez-les.
- Utilisation d'une clé secrète incorrecte. Chaque point de terminaison possède sa propre clé secrète. Utilisez la valeur complète, y compris
nd_whsec_, et la plus récente si vous l'avez renouvelée.
- L'horloge du serveur est mal réglée. Si l'horloge de votre serveur a un décalage de plus de quelques minutes, les requêtes valides apparaîtront comme trop anciennes. Synchronisez l'horloge, par exemple avec NTP.
- Comparer avec un simple test d'égalité. Utilisez une comparaison à temps constant, comme `
crypto.timingSafeEqual` dans Node.js ou `hmac.compare_digest` en Python.
Questions fréquentes
Pourquoi rejeter les requêtes datant de plus de 5 minutes ?
Une requête interceptée pourrait être renvoyée ultérieurement à votre serveur. La vérification de t limite cette possibilité à une courte période. Chaque nouvelle tentative est signée avec un nouveau t, ce qui permet leur validation.
L'événement de test est-il signé ?
Oui. Cliquez sur « Envoyer un événement de test » sur la page du point de terminaison pour vérifier votre code de vérification. La mention « 200 » sous « Livraisons récentes » indique que le test a réussi.
Puis-je revoir le secret de la signature ?
Non. Il n'est affiché qu'une seule fois, lors de l'ajout du point de terminaison ou de la rotation du secret. La page du point de terminaison n'affiche que ses premiers caractères.
Tous mes points de terminaison partagent-ils un même secret ?
Non. Chaque point de terminaison possède son propre secret de signature ; il faut donc vérifier chaque requête avec le secret du point de terminaison auquel elle a été envoyée.