Signierte Zustellungen — und eine E-Mail, die nichts verrät.

Eine Webhook-Adresse ist ein Geheimnis, das nach außen dringt. Sie landet in einem Ticket, in einer Chatnachricht, in einer Bildschirmaufnahme in einem Übergabedokument, im Browserverlauf eines gemeinsam genutzten Rechners. Ohne Signatur kann jeder, der die Adresse gesehen hat, beliebige Inhalte dorthin schicken, und Ihre Systeme legen sie als echte Antwort einer Beteiligung ab. Für eine Verwaltung, die Einwendungen gegen einen Bauantrag zählt, ist das kein theoretisches Problem.

Deshalb ist jede Zustellung signiert. Jeder Webhook erhält sein eigenes, zufällig erzeugtes Geheimnis, das im Editor hinter der Schaltfläche zum Anzeigen des Signaturgeheimnisses liegt. Wir bilden einen HMAC-SHA256 über die exakten Bytes des Nachrichtenrumpfs mit diesem Geheimnis; Sie bilden ihn mit Ihrer Kopie neu und vergleichen. Eine gefälschte Anfrage scheitert, weil der Fälschung das Geheimnis fehlt.

Die Adresse muss https sein. Das setzt eine Bedingung in der Datenbank durch und nicht ein Hinweis im Formular, denn ein Signaturgeheimnis, das über eine unverschlüsselte Verbindung reist, ist kein Geheimnis.

Eine Zustellung in Node.js prüfen

Zwei Einzelheiten richten in der Praxis den meisten Schaden an. Nehmen Sie den rohen Nachrichtenrumpf und kein ausgewertetes und neu serialisiertes Objekt — Unterschiede beim Leerraum verändern den Hash. Und vergleichen Sie in konstanter Zeit, damit niemand die richtige Signatur aus den Antwortzeiten Byte für Byte erschließen kann.

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

Rufen Sie das auf, bevor Sie irgendetwas auswerten. Ergibt es „falsch“, antworten Sie mit 401 und verwerfen die Anfrage. Ergibt es „wahr“, halten Sie eine Antwort in der Hand, die nur aus Ihrer Umfrage stammen kann.

Tragen Sie die Adressen ein, die von neuen Antworten erfahren sollen, und sie erhalten beim Eintreffen eine E-Mail. Die Nachricht ist gestaltetes HTML mit einer Nur-Text-Fassung, denn Nur-Text-Programme und Spam-Filter lesen beide den Textteil. Sie nennt die Umfrage, gibt den laufenden Gesamtstand an und verweist auf die Ergebnisse.

Was sie nicht enthält, sind die Antworten. Das ist eine Entscheidung und kein Versäumnis. Eine Benachrichtigungs-E-Mail wird an Kolleginnen weitergeleitet, automatisch in ein gemeinsames Postfach abgelegt, auf ein Telefon abgeglichen und jahrelang in Sicherungen aufbewahrt. Freitextantworten einer Beteiligung in diese Kette zu geben, streut personenbezogene Daten über Systeme, die niemand bewertet hat, und hebt still die Zugriffskontrollen auf, die die Seite zur Sicherheit beschreibt. Die Daten der Teilnehmenden bleiben in der Datenbank, und die E-Mail sagt Ihnen, dass Sie hineinsehen sollen.

Wie Webhooks lösen auch Benachrichtigungen über einen Datenbank-Trigger aus, sie folgen also der Antwort und nicht einem bestimmten Weg der Einreichung. Sind keine Adressen eingetragen, wird nichts geschickt und nichts versucht.