Webhooks

Registriere einen HTTPS-Endpoint, und Debaty sendet ein POST, sobald etwas passiert.

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

// Verify a Debaty webhook delivery, and reject anything that does not verify.
//   secret: the whsec_… shown once when you created the subscription
//   header: the X-Debaty-Signature request header (t=<seconds>,v1=<hex>)
//   body:   the raw, unparsed request body
function verifyDebatySignature(secret, header, body, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp)) return false;

  // The timestamp is inside the signed material, so a captured delivery cannot be
  // replayed later under a fresh t — reject anything outside the window.
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) return false;

  const expected = createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
  if (expected.length !== (parts.v1 ?? '').length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

1. Einen Endpunkt registrieren

   Gib eine HTTPS-URL an und wähle die Events aus, die du abhören willst. Über die API heißt dieses Feld eventTypes; die Referenz nennt die Werte, die es akzeptiert.

2. Die Signatur prüfen

   Jede Zustellung wird mit deinem Webhook-Secret signiert. Prüfe die Signatur, bevor du ihr vertraust.

3. Schnell antworten

   Antworte innerhalb von Sekunden mit einem 2xx. Bei einem Fehler versucht Debaty es erneut.

4. Was ankommt, und wann

   Du bekommst post.created, debate.created und comment.created. Alles, was über die API geschrieben wird, löst genau dieselben Events mit denselben Feldern aus wie alles, was über die Website geschrieben wird — du musst die Antwort eines Menschen also nie von der eines Bots unterscheiden.