Ondertekende afleveringen, en een e-mail die niets zegt.

Een webhook-adres is een geheim dat lekt. Het belandt in een ticket, in een Slack-bericht, in een schermafbeelding in een overdrachtsdocument, in de browsergeschiedenis van een gedeelde laptop. Zonder ondertekening kan iedereen die het adres heeft gezien er sturen wat hij wil, en uw systemen boeken dat weg als een echt consultatieantwoord. Voor een gemeente die bezwaren tegen een bouwaanvraag telt, is dat geen theoretisch probleem.

Daarom wordt elke aflevering ondertekend. Elke webhook krijgt een eigen, willekeurig gegenereerd geheim, dat in de editor achter een knop „ondertekengeheim tonen” zichtbaar wordt. Wij berekenen een HMAC-SHA256 over de exacte bytes van de inhoud van het verzoek met dat geheim; u berekent hem opnieuw met uw eigen kopie en vergelijkt. Een vervalst verzoek valt af, omdat de vervalser het geheim niet heeft.

Het adres moet https zijn. Dat wordt afgedwongen door een constraint in de database en niet door een aanwijzing in het formulier, omdat een ondertekengeheim dat over een onversleutelde verbinding reist geen geheim is.

Een aflevering controleren in Node.js

Twee details richten in de praktijk de meeste schade aan. Gebruik de onbewerkte inhoud van het verzoek en geen object dat is geparseerd en opnieuw is geserialiseerd — verschillen in witruimte veranderen de hash. En vergelijk met constante looptijd, zodat een aanvaller de juiste ondertekening niet byte voor byte kan afleiden uit de reactietijden.

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

Roep dat aan voordat u iets parseert. Geeft het false terug, antwoord dan met 401 en gooi het verzoek weg. Geeft het true terug, dan hebt u een antwoord dat alleen van uw enquête afkomstig kan zijn.

Voeg de adressen toe die over nieuwe antwoorden moeten horen, en zij krijgen een e-mail zodra er een binnenkomt. Het bericht is opgemaakte HTML met een alternatief in platte tekst, omdat zowel tekstprogramma's als spamfilters het platte deel lezen. Het noemt de enquête, geeft de lopende telling en verwijst naar de resultaten.

Wat er niet in staat, zijn de antwoorden. Dat is een besluit, geen omissie. Een meldingsmail wordt doorgestuurd naar een collega, automatisch weggeschreven in een gedeelde mailbox, gesynchroniseerd met een telefoon en jarenlang in een back-up bewaard. Vrije antwoorden uit een consultatie in die keten stoppen, verspreidt persoonsgegevens over systemen die niemand heeft beoordeeld, en ondermijnt stilletjes de toegangscontroles die op de pagina over beveiliging staan beschreven. Gegevens van respondenten blijven in de database, en de e-mail zegt u dat u even moet gaan kijken.

Net als webhooks worden meldingen in gang gezet door een databasetrigger, dus ze volgen het antwoord in plaats van een bepaalde route van indienen. Zijn er geen adressen ingesteld, dan wordt er niets verstuurd en niets geprobeerd.