Sicherheit

Die Zuverlässigkeit von Webhooks hängt sowohl vom Verhalten Ihres Endpunkts als auch von den Liefergarantien von Unico ab. Diese Seite behandelt die drei Invarianten, die Ihr Endpunkt einhalten muss: Idempotenz, Parallelitätslimit und Fehlerrate.

Idempotenz

Unicos Webhook-Implementierung garantiert At-Least-Once-Delivery — derselbe Status kann für dieselbe processId mehrfach gemeldet werden. Ihr Endpunkt muss idempotent sein.

Empfohlenes Muster:

1. Prüfen Sie bei jedem Webhook-Aufruf zunächst, ob die processId bereits verarbeitet wurde.
2. Falls ja, geben Sie sofort 2xx zurück (die Arbeit ist bereits erledigt).
3. Falls nicht, wenden Sie Ihre Geschäftslogik an und speichern Sie, dass diese processId verarbeitet wurde.

// pseudo-code
async function handleWebhook(req, res) {
  const { processId } = req.body;

  if (await alreadyProcessed(processId)) {
    return res.status(200).end();
  }

  await applyBusinessLogic(req.body);
  await markAsProcessed(processId);
  return res.status(200).end();
}

Warum das wichtig ist

Ein nicht-idempotenter Endpunkt, der bei jeder Lieferung Geschäftslogik ausführt (z. B. eine Karte belastet, eine E-Mail versendet), wird mehrfach ausgelöst, wenn ein Retry erfolgt — und Retries sind normal, keine Ausnahme, bei der Webhook-Lieferung.

Parallelitätslimit

Um Ihren Endpunkt vor Spitzen in Hochvolumenzeiten zu schützen, konfigurieren Sie beim Registrieren des Webhooks eine maximale Anzahl gleichzeitiger aktiver Lieferungen (max: 500).

Wenn das Parallelitätslimit erreicht ist, stellt Unico zusätzliche Lieferungen in die Warteschlange und verarbeitet sie, sobald Kapazität verfügbar wird. In Kombination mit Retries kann eine anhaltende Spitze die effektive Lieferzeit neuer Webhooks verlängern.

Fehlerrate

Die Fehlerrate (Antworten außerhalb des 200–299-Bereichs) sollte stets niedrig sein. Wenn Ihr Endpunkt im großen Maßstab Fehler zurückgibt, reduziert Unico automatisch den Webhook-Durchsatz für diesen Endpunkt. In Kombination mit dem Retry-Mechanismus kann dies die Ausführungszeit neuer Webhooks erheblich verlängern.

Betriebliche Hinweise:

• Überwachen Sie Nicht-2xx-Antworten auf Ihrer Seite. Alertieren Sie bei anhaltenden Fehlerraten über Ihrer normalen Basislinie.
• Behandeln Sie Ihren Webhook-Handler als kritischen Pfad — er sollte zu den zuverlässigsten Diensten in Ihrem Stack gehören.
• Bei geplanter Wartung sollten Sie die Aufnahme am Load Balancer stoppen, anstatt 503 zurückzugeben. Anhaltende Nicht-2xx-Antworten — einschließlich 503 — aktivieren die oben beschriebene automatische Durchsatzdrosselung; wenn Ihr Endpunkt sich erholt, verzögert der reduzierte Durchsatz die Auslieferung der während des Ausfalls in der Warteschlange angesammelten Ereignisse. Geben Sie nicht 200 für unverarbeitete Ereignisse zurück.

Status-Semantik

Behandeln Sie die Menge der state- und lastEvent-Werte als veränderliche Konfiguration:

• Reagieren Sie nur auf Zustände / Ereignisse, die Sie explizit behandeln.
• Protokollieren Sie unbekannte Werte — geben Sie bei diesen keine Fehler aus.
• Neue Zustände können ohne eine Major-Version-Änderung hinzugefügt werden.