Cada solicitud de webhook se firma con la clave secreta de firma de tu endpoint. Verifica la firma antes de confiar en una solicitud, para que tu servidor solo procese eventos que realmente provengan de Notiondesk y que no hayan sido modificados durante el proceso.
tv1X-ND-Signature{t}.{raw body}v1Antes de empezar
- Tienes la clave secreta de firma que copiaste al agregar el punto final. Comienza con
nd_whsec_. Si la perdiste, rótala. Consulta Rotar la clave secreta de firma .
- El receptor puede leer el cuerpo de la solicitud exactamente como llegó, antes de cualquier análisis JSON.
Cómo funciona la firma
Cada solicitud tiene un encabezado X-ND-Signature:
X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb| Parte | Qué es |
|---|---|
t | Cuando se envió la solicitud, en segundos desde el 1 de enero de 1970 (UTC). Cada reintento obtiene un nuevo t. |
v1 | El HMAC SHA-256 de t, un punto y el cuerpo de la solicitud sin procesar, firmado con su clave secreta de firma y escrito en minúsculas hexadecimales. |
Verificar una solicitud
- Lee el cuerpo de la solicitud sin procesar, como bytes. No lo analices primero.
- Divida el encabezado
X-ND-Signaturepor comas y leatyv1.
- Construye el texto firmado:
t, un punto, luego el cuerpo sin formato. Por ejemplo,1794955939.{"id":"019a8f2e-...",...}.
- Calcula un HMAC SHA-256 de ese texto con tu clave secreta de firma completa, incluyendo
nd_whsec_, y escríbelo en minúsculas hexadecimales.
- Compara tu resultado con
v1usando una comparación de tiempo constante.
- Comprueba que
testé dentro de los 5 minutos de la hora de tu servidor.
- Si alguna comprobación falla, responda
400e ignore la solicitud. Si todas son correctas, responda200y gestione el evento.
Ejemplo de Node.js
Esto funciona con Node.js 18 o posterior y Express. express.raw mantiene el cuerpo como bytes sin procesar, que es lo que necesita la firma.
Ejemplo de Python
Esto funciona con Python 3.9 o posterior y Flask. request.get_data() devuelve el cuerpo sin procesar.
Gire el secreto de firma
Cambia la clave secreta si se ha filtrado o si la has perdido.
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- Abra el punto final en Configuración > Desarrolladores > Webhooks .
- En la sección "Secreto de firma" , haga clic en "Girar" y, a continuación, vuelva a girar para confirmar.
- Copia el nuevo secreto, guárdalo en tu servidor y luego haz clic en "Lo guardé" .
Si algunas solicitudes fallan mientras realiza el cambio, se volverán a intentar después de 1 minuto con la nueva clave secreta.
Errores comunes
- Se comprueba el JSON analizado en lugar del cuerpo sin procesar. Analizar el cuerpo y convertirlo de nuevo a texto modifica el espaciado y el escape, por lo que la firma ya no coincide. Verifique los bytes recibidos y, a continuación, analícelos.
- Estás usando la clave secreta incorrecta. Cada punto final tiene su propia clave secreta. Usa el valor completo, incluyendo
nd_whsec_, y la última si la has rotado.
- Reloj del servidor desincronizado. Si el reloj de su servidor está desfasado por más de unos minutos, las solicitudes válidas aparecerán como antiguas. Mantenga el reloj sincronizado, por ejemplo, con NTP.
- Comparación con una simple comprobación de igualdad. Utilice una comparación de tiempo constante, como
crypto.timingSafeEqualen Node.js ohmac.compare_digesten Python.
Preguntas frecuentes
¿Por qué rechazar las solicitudes con más de 5 minutos de antigüedad?
Una solicitud capturada podría enviarse nuevamente a su servidor más tarde. La comprobación de t limita esto a un breve período. Cada reintento se firma con un nuevo t, por lo que los reintentos siguen siendo válidos.
¿Está firmado el evento de prueba?
Sí. Haz clic en Enviar evento de prueba en la página del punto final para comprobar tu código de verificación. Si aparece 200 en Entregas recientes, significa que la prueba se realizó correctamente.
¿Puedo ver de nuevo el secreto de la firma?
No. Se muestra una sola vez, al agregar el punto final o rotar el secreto. La página del punto final solo muestra sus primeros caracteres.
¿Todos mis puntos finales comparten un mismo secreto?
No. Cada punto final tiene su propia clave secreta de firma, así que compruebe cada solicitud con la clave secreta del punto final al que se envió.