Vérifiez que le webhook provient bien de Notiondesk

Vérifiez l'en-tête X-ND-Signature des requêtes webhook Notiondesk avec votre secret de signature, avec des exemples testés en Node.js et Python.

5 minutes de lecture

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.

Chemin rapide : Lisez l’en-tête, calculez un HMAC SHA-256 avec votre secret de signature, comparez-le et rejetez les requêtes datant de plus de 5 minutes.tv1X-ND-Signature{t}.{raw body}v1

Avant 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
tDate d'envoi de la requête, en secondes depuis le 1er janvier 1970 (UTC). Chaque nouvelle tentative se voit attribuer une nouvelle valeur t.
v1Le 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

  1. Lisez le corps brut de la requête sous forme d'octets. Ne l'analysez pas au préalable.
  1. Divisez l'en-tête X-ND-Signature en virgules et lisez t et v1.
  1. Constituez le texte signé : t, un point, puis le corps brut. Par exemple : 1794955939.{"id":"019a8f2e-...",...}.
  1. 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.
  1. Comparez votre résultat avec v1 en utilisant une comparaison à temps constant.
  1. Vérifiez que t correspond à l'heure de votre serveur dans les 5 minutes qui s'y rattachent.
  1. En cas d'échec d'une vérification, répondre 400 et ignorer la requête. En cas de réussite, répondre 200 et 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
  1. Ouvrez le point de terminaison dans Paramètres > Développeurs > Webhooks .
  1. Sous « Secret de signature » , cliquez sur « Rotation » , puis à nouveau sur « Rotation » pour confirmer.
  1. Copiez le nouveau secret, stockez-le sur votre serveur, puis cliquez sur « Je l'ai enregistré » .
L'ancien secret cesse immédiatement de fonctionner. Chaque requête envoyée après la rotation, y compris les nouvelles tentatives d'événements antérieurs, est signée avec le nouveau secret ; assurez-vous donc de mettre à jour votre serveur simultanément.

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.

Articles associés

Cette page a-t-elle été utile ?

Encore besoin d'aide ? Écrivez-nous