Webhooks erklärt: Signierte Payloads & zuverlässige Retries

Backend2026-11-11TryQuickToolBox

Du hast eine Payment-Integration ausgeliefert und in der Staging-Umgebung funktioniert alles. Dann zahlt in der Produktion ein Kunde, dein Endpoint läuft für zwei Sekunden in ein Timeout und die Bestellung wird nie aktiviert. Währenddessen wiederholt der Payment-Provider dasselbe Event dreimal, und deine App erzeugt drei doppelte Bestellungen für die eine, die erfolgreich war. Webhooks sehen einfach aus – nur ein HTTP-POST –, aber die schwierigen Teile sind Vertrauen und Zustellgarantien.

Dieser Artikel behandelt die zwei Dinge, die Webhook-Integrationen am häufigsten brechen: zu verifizieren, dass eine Anfrage wirklich vom Absender kam, und Retries ohne doppelte Seiteneffekte zu handhaben.

Was ein Webhook eigentlich ist

Ein Webhook ist ein umgekehrter API-Aufruf. Statt dass dein Server den Provider jede Minute abfragt („gibt es etwas Neues?“), schickt der Provider eine HTTP-Anfrage an eine URL, die du registriert hast, sobald ein Event eintritt. Der Payload ist normalerweise JSON, und der Event-Typ steht entweder im Body oder in einem Header.

POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Event-Id: evt_8f2c1a
X-Timestamp: 1735689600
X-Signature: t=1735689600,v1=5d41402abc4b2a76b9719d911017c592

{
  "id": "evt_8f2c1a",
  "type": "payment.succeeded",
  "created": 1735689600,
  "data": { "order_id": "ord_123", "amount": 4999, "currency": "USD" }
}

Auf der Senderseite sind zwei Design-Entscheidungen wichtig, und du solltest beide prüfen, wenn du einen Provider bewertest: Signiert er den Payload, und wiederholt er bei Fehlern?

Warum unsignierte Webhooks gefährlich sind

Deine Webhook-URL ist öffentlich. Jeder, der sie erfährt, kann ein gefälschtes payment.succeeded-Event POSTen und eine unbezahlte Bestellung als bezahlt markieren. Eine IP-Allowlist hilft ein wenig, aber Provider wechseln IPs, laufen hinter CDNs, und du bekommst möglicherweise keine stabile Liste.

Die robuste Antwort ist eine HMAC-Signatur über den rohen Request-Body mit einem gemeinsamen Secret, das nur du und der Provider kennen. Der Provider berechnet die Signatur und sendet sie in einem Header; du berechnest sie neu und vergleichst.

Eine Signatur korrekt verifizieren

Drei Details gehen leicht schief:

// Node.js / Express example
const crypto = require('crypto');

function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('='))
  );
  const timestamp = Number(parts.t);
  if (!timestamp) return false;

  // Reject stale requests (replay protection)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/payments', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifySignature(req.body.toString(), req.get('X-Signature'), SECRET)) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  // ... handle event
  res.status(200).send('ok');
});

Beachte die express.raw()-Middleware. Wenn du express.json() vor dieser Route mountest, ist der Body bereits geparst und die Signaturprüfung schlägt stillschweigend fehl – ein sehr häufiger Bug.

Retries entwerfen, die keine Events verlieren

Webhook-Zustellung ist at-least-once, nicht exactly-once. Netzwerke fallen aus, dein Deploy startet einen Container neu, und der Provider hat keine Ahnung, ob deine 200-Antwort echt war. Also wiederholt der Provider mit exponentiellem Backoff, oft über Stunden oder Tage.

Schnell antworten, später verarbeiten

Dein Endpoint sollte das Minimum tun: verifizieren, das rohe Event persistieren, 2xx zurückgeben. Schwere Arbeit – E-Mails senden, andere APIs aufrufen, Rechnungen generieren – sollte in einem Background-Job passieren. Wenn die Verarbeitung länger dauert als das Timeout des Providers, wird die Anfrage als fehlgeschlagen behandelt und wiederholt, obwohl du die Arbeit erledigt hast.

  1. Verifiziere die Signatur und den Timestamp.
  2. Füge das Event in eine Tabelle mit einem Unique-Constraint auf die Event-ID ein.
  3. Gib sofort 200 zurück.
  4. Verarbeite das gespeicherte Event asynchron und markiere es als erledigt.

Idempotenz: die eigentliche Lösung für Duplikate

Weil Retries passieren, muss dein Handler sicher zweimal laufen können. Die Event-ID ist der natürliche Idempotenz-Key.

INSERT INTO webhook_events (event_id, type, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;

Wenn der Insert null Zeilen betrifft, hast du dieses Event schon gesehen – bestätige es und mach weiter. Für die Geschäftslogik gilt dieselbe Idee: Verwende die Order-ID als Unique-Key beim Aktivieren einer Zahlung, damit ein zweites Event keine zweite Aktivierung erzeugen kann.

Statuscodes bewusst wählen

StatusProvider-VerhaltenWann verwenden
200 / 204Als zugestellt markierenEvent akzeptiert (auch wenn bereits verarbeitet)
400Meist kein RetryMalformed Payload, den du nie verarbeiten kannst
401Meist kein RetrySignatur-Mismatch – prüfe dein Secret
429Retry mit BackoffDu limitierst die Rate
500 / 503Retry mit BackoffTemporärer Fehler, DB down, Deploy läuft

Ein 200 für ein Event zurückzugeben, das du nicht speichern konntest, ist die schlechteste Option: Der Provider hört auf zu wiederholen und das Event ist für immer weg. Gib ein 5xx zurück und lass den Retry seine Arbeit tun.

Praktische Checkliste für die Produktion

Webhooks lokal testen

Du kannst nicht einfach einen öffentlichen POST auf localhost empfangen. Optionen: ein Tunneling-Tool, das deinen Dev-Port exponiert, die CLI des Providers, falls es eine gibt, oder ein kleines Skript, das einen signierten Payload an deinen Handler sendet, damit du den Verifikationspfad testen kannst.

Der wertvollste Test ist das Duplikat: Sende dasselbe Event zweimal und bestätige, dass dein System im selben Zustand endet. Sende dann ein Event mit einem alten Timestamp und bestätige, dass es abgelehnt wird. Manipuliere dann ein Byte des Bodys und bestätige, dass die Signaturprüfung fehlschlägt.

Payloads debuggen

Webhook-Bodys sind JSON, und malformed oder tief verschachtelte Payloads sind in Logs mühsam zu lesen. Ein Formatter hilft dir, die Struktur schnell zu inspizieren, bevor du Parsing-Code schreibst. Der JSON-Formatter läuft im Browser, sodass du einen erfassten Payload einfügen kannst, ohne Kundendaten an einen Server zu senden.

FAQ

Was ist der Unterschied zwischen einem Webhook und einer API?

Eine API ist Pull-basiert: Dein Code ruft den Provider auf, wenn er Daten braucht. Ein Webhook ist Push-basiert: Der Provider ruft deinen Endpoint auf, wenn ein Event eintritt. Die meisten Integrationen nutzen beides – Webhooks für Event-Benachrichtigungen und die API, um vollständige Details abzurufen oder Aktionen auszuführen.

Warum stimmt meine HMAC-Signatur nie überein?

Die übliche Ursache ist das Signieren eines re-serialisierten Bodys statt der rohen Bytes. Whitespace, Schlüsselreihenfolge und Unicode-Escaping ändern alle den Hash. Lies den rohen Request-Body vor jeder JSON-Middleware und bestätige, dass Secret und Hash-Algorithmus mit der Dokumentation des Providers übereinstimmen.

Sind Webhook-Retries garantiert?

Nein. Provider wiederholen typischerweise für ein begrenztes Zeitfenster mit exponentiellem Backoff und geben dann auf. Behandle Webhooks als schnellen Benachrichtigungskanal statt als Source of Truth: Gleiche periodisch gegen die API des Providers ab, damit verpasste Events irgendwann korrigiert werden.

Wenn du heute einen Webhook-Receiver baust oder debuggst, beginne mit der Absicherung der Signaturverifikation und idempotenter Speicherung – diese beiden Änderungen eliminieren die Mehrheit der realen Webhook-Vorfälle.