Entregas firmadas y un correo que no dice nada.

La URL de un webhook es un secreto que se filtra. Acaba en una incidencia, en un mensaje de Slack, en una captura dentro de un documento de traspaso, en el historial de un portátil compartido. Sin firma, cualquiera que haya visto la URL puede enviarle lo que quiera, y sus sistemas lo archivarán como una respuesta auténtica a una consulta. Para un ayuntamiento que cuenta alegaciones a un expediente urbanístico, eso no es un problema teórico.

Por eso cada entrega va firmada. Cada webhook recibe su propio secreto generado al azar, visible en el editor tras un control de «mostrar secreto de firma». Nosotros calculamos un HMAC-SHA256 sobre los bytes exactos del cuerpo de la petición con ese secreto; usted lo recalcula con su copia y compara. Una petición falsificada no pasa, porque quien la falsifica no tiene el secreto.

La URL debe ser https. Lo impone una restricción de base de datos, no una indicación en el formulario, porque un secreto de firma que viaja por una conexión sin cifrar no es un secreto.

Verificar una entrega en Node.js

Dos detalles causan casi todos los problemas en la práctica. Use el cuerpo en bruto de la petición, no un objeto analizado y vuelto a serializar: las diferencias de espacios en blanco cambian el hash. Y compare en tiempo constante, para que nadie pueda deducir la firma correcta byte a byte a partir de los tiempos de respuesta.

import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRET = process.env.NOISSIME_WEBHOOK_SECRET;

// rawBody must be the exact bytes received, before any JSON parsing.
// Re-serialising a parsed object changes the whitespace and the check fails.
function isFromNoissime(rawBody, header) {
  if (typeof header !== 'string') return false;

  const expected =
    'sha256=' + createHmac('sha256', SECRET).update(rawBody).digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(header);

  // timingSafeEqual throws on a length mismatch, so compare lengths first.
  return a.length === b.length && timingSafeEqual(a, b);
}

Llame a eso antes de analizar nada. Si devuelve falso, responda 401 y descarte la petición. Si devuelve verdadero, tiene una respuesta que solo puede proceder de su encuesta.

Añada las direcciones que deban enterarse de las nuevas respuestas y recibirán un correo cuando llegue una. El mensaje es HTML con la marca y con una alternativa en texto plano, porque tanto los clientes de solo texto como los filtros antispam leen la parte de texto. Nombra la encuesta, da el total acumulado de respuestas y enlaza a los resultados.

Lo que no contiene son las respuestas. Es una decisión, no un olvido. Un correo de aviso se reenvía a un compañero, se archiva automáticamente en un buzón compartido, se sincroniza con un móvil y se conserva en una copia de seguridad durante años. Meter en esa cadena respuestas de texto libre de una consulta dispersa datos personales por sistemas que nadie ha evaluado y deshace discretamente los controles de acceso que se describen en la página de seguridad. Los datos de quien responde se quedan en la base de datos, y el correo le dice que vaya a mirarlos.

Igual que los webhooks, los avisos los dispara un disparador de base de datos, así que siguen a la respuesta y no a una vía de envío concreta. Si no hay ninguna dirección configurada, no se envía nada ni se intenta nada.