Ogni richiesta webhook è firmata con il segreto di firma del tuo endpoint. Verifica la firma prima di considerare attendibile una richiesta, in modo che il tuo server agisca solo sugli eventi che provengono effettivamente da Notiondesk e non sono stati modificati durante il percorso.
tv1X-ND-Signature{t}.{raw body}v1Prima di iniziare
- Hai a disposizione il segreto di firma che hai copiato quando hai aggiunto l'endpoint. Inizia con
nd_whsec_. Se lo hai perso, ruotalo. Vedi Ruotare il segreto di firma .
- Il destinatario può leggere il corpo della richiesta esattamente come è arrivato, prima di qualsiasi analisi JSON.
Come funziona la firma
Ogni richiesta ha un'intestazione X-ND-Signature:
X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb| Parte | Che cos'è |
|---|---|
t | Quando la richiesta è stata inviata, in secondi dal 1 gennaio 1970 (UTC). Ogni tentativo successivo ottiene un nuovo t |
v1 | L'HMAC SHA-256 di t, un punto e il corpo della richiesta raw, firmato con il tuo segreto di firma e scritto in esadecimale minuscolo |
Verifica una richiesta
- Leggi il corpo della richiesta non elaborato come byte. Non analizzarlo prima.
- Dividi l'intestazione
X-ND-Signaturein base alle virgole e leggitev1.
- Costruisci il testo firmato:
t, un punto, quindi il corpo grezzo. Ad esempio1794955939.{"id":"019a8f2e-...",...}.
- Calcola l'hash SHA-256 HMAC di quel testo con il tuo segreto di firma completo, incluso
nd_whsec_, e scrivilo in esadecimale minuscolo.
- Confronta il tuo risultato con
v1utilizzando un confronto a tempo costante.
- Verifica che
tsia entro 5 minuti dall'orario del tuo server.
- Se uno qualsiasi dei controlli fallisce, rispondi
400e ignora la richiesta. Se tutti i controlli hanno esito positivo, rispondi200e gestisci l'evento.
Esempio Node.js
Questo funziona con Node.js 18 o versioni successive ed Express. express.raw mantiene il corpo come byte grezzi, necessari per la firma.
Esempio Python
Questo funziona con Python 3.9 o versioni successive e Flask. request.get_data() restituisce il corpo grezzo.
Ruota il segreto di firma
Ruota il segreto se potrebbe essere trapelato o se lo hai perso.
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- Apri l'endpoint in Impostazioni > Sviluppatori > Webhooks .
- Nella sezione "Segreto di firma" , fai clic su "Ruota" , quindi ruota di nuovo per confermare.
- Copia il nuovo segreto, memorizzalo sul tuo server, quindi fai clic su "L'ho salvato" .
Se durante il passaggio alcune richieste falliscono, verranno ritentate dopo 1 minuto con la nuova chiave segreta.
Errori comuni
- Verifichiamo il JSON analizzato anziché il corpo grezzo. L'analisi del corpo e la sua riconversione in testo modificano la spaziatura e i caratteri di escape, pertanto la firma non corrisponde più. Verifichiamo i byte ricevuti, quindi procediamo con l'analisi.
- Utilizzo del segreto errato. Ogni endpoint ha il proprio segreto. Utilizzare il valore completo, incluso
nd_whsec_, e l'ultimo se è stato ruotato.
- Un orologio del server errato. Se l'orologio del server è sfasato di più di qualche minuto, le richieste valide risulteranno obsolete. Mantieni l'orologio sincronizzato, ad esempio tramite NTP.
- Confronto tramite un semplice controllo di uguaglianza. Utilizzare un confronto a tempo costante, come
crypto.timingSafeEqualin Node.js ohmac.compare_digestin Python.
Domande frequenti
Perché rifiutare le richieste più vecchie di 5 minuti?
Una richiesta intercettata potrebbe essere inviata nuovamente al tuo server in un secondo momento. Il controllo t limita tale intervallo a una finestra temporale breve. Ogni nuovo tentativo viene firmato nuovamente con un nuovo t, quindi i tentativi successivi hanno comunque esito positivo.
L'evento di test è stato firmato?
Sì. Fai clic su Invia evento di test nella pagina dell'endpoint per controllare il codice di verifica. La dicitura 200 sotto Consegne recenti indica che il test è andato a buon fine.
Posso rivedere il segreto della firma?
No. Viene visualizzato una sola volta, quando si aggiunge l'endpoint o si ruota il segreto. La pagina dell'endpoint mostra solo i suoi primi caratteri.
Tutti i miei endpoint condividono un unico segreto?
No. Ogni endpoint ha il proprio segreto di firma, quindi verifica ogni richiesta con il segreto dell'endpoint a cui è stata inviata.