Verifica che il webhook provenga da Notiondesk

Verifica l'intestazione X-ND-Signature nelle richieste webhook Notiondesk con il tuo segreto di firma, con esempi testati in Node.js e Python.

4 min di lettura

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.

Percorso rapido: Leggi e dall'intestazione, calcola un HMAC SHA-256 con il tuo segreto di firma, confrontalo e rifiuta le richieste più vecchie di 5 minuti.tv1X-ND-Signature{t}.{raw body}v1

Prima 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'è
tQuando la richiesta è stata inviata, in secondi dal 1 gennaio 1970 (UTC). Ogni tentativo successivo ottiene un nuovo t
v1L'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

  1. Leggi il corpo della richiesta non elaborato come byte. Non analizzarlo prima.
  1. Dividi l'intestazione X-ND-Signature in base alle virgole e leggi t e v1.
  1. Costruisci il testo firmato: t, un punto, quindi il corpo grezzo. Ad esempio 1794955939.{"id":"019a8f2e-...",...}.
  1. Calcola l'hash SHA-256 HMAC di quel testo con il tuo segreto di firma completo, incluso nd_whsec_, e scrivilo in esadecimale minuscolo.
  1. Confronta il tuo risultato con v1 utilizzando un confronto a tempo costante.
  1. Verifica che t sia entro 5 minuti dall'orario del tuo server.
  1. Se uno qualsiasi dei controlli fallisce, rispondi 400 e ignora la richiesta. Se tutti i controlli hanno esito positivo, rispondi 200 e 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
  1. Apri l'endpoint in Impostazioni > Sviluppatori > Webhooks .
  1. Nella sezione "Segreto di firma" , fai clic su "Ruota" , quindi ruota di nuovo per confermare.
  1. Copia il nuovo segreto, memorizzalo sul tuo server, quindi fai clic su "L'ho salvato" .
Il vecchio segreto smette di funzionare immediatamente. Ogni richiesta inviata dopo la rotazione, inclusi i tentativi di eventi precedenti, viene firmata con il nuovo segreto, quindi aggiorna il tuo server contemporaneamente.

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.timingSafeEqual in Node.js o hmac.compare_digest in 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.

Articoli correlati

Questa pagina è stata utile?

Still need help? Ask us