Livrări semnate și un e-mail care nu spune nimic.

Un URL de webhook este un secret care se scurge. Ajunge într-un tichet, într-un mesaj de Slack, într-o captură de ecran dintr-un document de predare-primire, în istoricul unui browser de pe un laptop folosit în comun. Fără semnătură, oricine a văzut URL-ul poate trimite acolo ce dorește, iar sistemele dumneavoastră vor înregistra rezultatul ca pe un răspuns real la consultare. Pentru un consiliu local care numără obiecțiile la o cerere de autorizare, aceasta nu este o problemă teoretică.

Prin urmare, fiecare livrare este semnată. Fiecare webhook primește propriul secret generat aleatoriu, afișat în editor în spatele unui control de tip „arată secretul de semnare”. Noi calculăm un HMAC-SHA256 peste octeții exacți ai corpului cererii, folosind acel secret; dumneavoastră îl recalculați cu copia proprie și comparați. O cerere falsificată eșuează, pentru că falsificatorul nu are secretul.

URL-ul trebuie să fie https. Acest lucru este impus de o constrângere din baza de date, nu de o simplă indicație în formular, pentru că un secret de semnare care călătorește pe o conexiune necriptată nu mai este un secret.

Verificarea unei livrări în Node.js

Două detalii produc, în practică, cele mai multe pagube. Folosiți corpul brut al cererii, nu un obiect analizat și reserializat — diferențele de spații albe schimbă hashul. Și comparați în timp constant, ca un atacator să nu poată afla semnătura corectă octet cu octet, din timpii de răspuns.

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

Apelați funcția înainte de a analiza orice altceva. Dacă returnează false, răspundeți cu 401 și aruncați cererea. Dacă returnează true, aveți un răspuns care nu putea veni decât de la chestionarul dumneavoastră.

Adăugați adresele care ar trebui să afle despre răspunsurile noi și li se va trimite un e-mail la sosirea fiecăruia. Mesajul este HTML personalizat, cu o alternativă în text simplu, pentru că atât clienții de e-mail care afișează doar text, cât și filtrele antispam citesc partea simplă. E-mailul numește chestionarul, dă totalul curent al răspunsurilor și trimite către rezultate.

Ce nu conține sunt răspunsurile. Aceasta este o decizie, nu o omisiune. Un e-mail de notificare este redirecționat unui coleg, arhivat automat într-o căsuță comună, sincronizat pe un telefon și păstrat ani întregi într-o copie de siguranță. Introducerea în acest lanț a răspunsurilor de text liber dintr-o consultare împrăștie date cu caracter personal prin sisteme pe care nu le-a evaluat nimeni și anulează pe tăcute controalele de acces descrise în pagina de securitate. Datele respondenților rămân în baza de date, iar e-mailul vă spune doar să mergeți să vă uitați.

La fel ca webhookurile, notificările sunt declanșate de un declanșator din baza de date, deci urmează răspunsul, nu o anumită cale de trimitere. Dacă nu este configurată nicio adresă, nu se trimite nimic și nu se încearcă nimic.