Entregas assinadas, e um e-mail que não diz nada.

Um URL de webhook é um segredo que se derrama. Acaba num pedido de assistência, numa mensagem de Slack, numa captura de ecrã de um documento de transição, no histórico de um portátil partilhado. Sem assinatura, quem tiver visto o URL pode enviar-lhe o que quiser, e os seus sistemas arquivam isso como uma resposta genuína a uma consulta pública. Para uma autarquia a contar oposições a um pedido de licenciamento, isso não é um problema teórico.

Por isso, todas as entregas são assinadas. Cada webhook recebe o seu segredo gerado aleatoriamente, mostrado no editor por trás de um controlo de «mostrar segredo de assinatura». Calculamos um HMAC-SHA256 sobre os bytes exatos do corpo do pedido com esse segredo; do seu lado recalcula-o com a sua cópia e compara. Um pedido forjado falha, porque quem o forjou não tem o segredo.

O URL tem de ser https. Isso é imposto por uma restrição da base de dados, e não por uma sugestão no formulário, porque um segredo de assinatura a viajar por uma ligação não cifrada não é um segredo.

Verificar uma entrega em Node.js

Na prática, dois pormenores causam quase todos os problemas. Use o corpo do pedido em bruto, e não um objeto interpretado e voltado a serializar — diferenças de espaços em branco alteram o resumo. E compare em tempo constante, para que um atacante não consiga aprender a assinatura correta byte a byte a partir dos tempos de resposta.

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);
}

Invoque isso antes de interpretar seja o que for. Se devolver falso, responda 401 e descarte o pedido. Se devolver verdadeiro, tem uma resposta que só pode ter vindo do seu inquérito.

Acrescente os endereços que devem saber das novas respostas e passam a receber um e-mail quando chega uma. A mensagem é HTML com a sua imagem e uma alternativa em texto simples, porque tanto os clientes só de texto como os filtros de spam leem a parte simples. Indica o inquérito, dá o total acumulado de respostas e liga aos resultados.

O que não contém são as respostas. Isso é uma decisão, não uma omissão. Um e-mail de notificação é reencaminhado a um colega, arquivado automaticamente numa caixa partilhada, sincronizado com um telemóvel e conservado numa cópia de segurança durante anos. Colocar respostas de texto livre de uma consulta pública nessa cadeia espalha dados pessoais por sistemas que ninguém avaliou e desfaz discretamente os controlos de acesso descritos na página de segurança. Os dados de quem responde ficam na base de dados, e o e-mail diz-lhe para ir ver.

Tal como os webhooks, as notificações são despoletadas por um acionador de base de dados, pelo que seguem a resposta e não uma via de submissão em concreto. Se não estiver configurado nenhum endereço, nada é enviado e nada é sequer tentado.