Verifica que el webhook provenga de Notiondesk

Compruebe el encabezado X-ND-Signature en las solicitudes de webhook Notiondesk con su clave secreta de firma, con ejemplos probados en Node.js y Python.

5 min de lectura

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.

Ruta rápida: Lea y a partir del encabezado, calcule un HMAC SHA-256 con su secreto de firma, compárelo con y rechace las solicitudes con más de 5 minutos de antigüedad.tv1X-ND-Signature{t}.{raw body}v1

Antes 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
tCuando se envió la solicitud, en segundos desde el 1 de enero de 1970 (UTC). Cada reintento obtiene un nuevo t.
v1El 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

  1. Lee el cuerpo de la solicitud sin procesar, como bytes. No lo analices primero.
  1. Divida el encabezado X-ND-Signature por comas y lea t y v1.
  1. Construye el texto firmado: t, un punto, luego el cuerpo sin formato. Por ejemplo, 1794955939.{"id":"019a8f2e-...",...}.
  1. 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.
  1. Compara tu resultado con v1 usando una comparación de tiempo constante.
  1. Comprueba que t esté dentro de los 5 minutos de la hora de tu servidor.
  1. Si alguna comprobación falla, responda 400 e ignore la solicitud. Si todas son correctas, responda 200 y 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
  1. Abra el punto final en Configuración > Desarrolladores > Webhooks .
  1. En la sección "Secreto de firma" , haga clic en "Girar" y, a continuación, vuelva a girar para confirmar.
  1. Copia el nuevo secreto, guárdalo en tu servidor y luego haz clic en "Lo guardé" .
La clave secreta antigua deja de funcionar inmediatamente. Cada solicitud enviada después de la rotación, incluidos los reintentos de eventos anteriores, se firma con la nueva clave secreta, así que actualice su servidor al mismo tiempo.

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

Artículos relacionados

¿Fue útil esta página?

Still need help? Ask us