Webhooks

ObjectOS verwendet ein persistentes Outbox-Modell für ausgehende Webhooks. Wenn das Webhook-Plugin aktiviert ist, reihen Geschäftsänderungen eine Zustellungszeile in die Warteschlange ein, und ein Hintergrund-Dispatcher stellt sie mit erneuten Versuchen zu — sodass ein langsamer oder nicht verfügbarer Empfänger niemals die auslösende Transaktion blockiert.

Webhooks aktivieren

Webhooks sind eine optionale Funktion. Das bereitgestellte ObjectOS-Image muss @objectstack/plugin-webhooks enthalten, und das Anwendungsartefakt muss Webhook-Abonnements registrieren (typischerweise als Datensätze eines sys_webhook-Objekts).

Wenn aktiviert, erscheinen zwei Objekte in der Console:

Zustellungssemantik

• At-least-once. Eine Zustellung kann nach einem vorübergehenden Fehler erneut versucht werden; Empfänger müssen idempotent sein.
• Persistent. Zustellungen überstehen ObjectOS-Neustarts, da sie in der Geschäftsdatenbank gespeichert sind.
• Partitioniert. Jeder Dispatcher-Worker beansprucht eine Partition der Outbox, sodass Deployments den Versand horizontal skalieren können, ohne doppelte Zustellung.
• Begrenzte erneute Versuche. Fehlgeschlagene Zustellungen werden mit Backoff bis zu einer konfigurierbaren Obergrenze erneut versucht; erschöpfte Zeilen verbleiben zur Inspektion in sys_webhook_delivery.

Signierung

Jede Zustellung trägt identifizierende Header, damit Empfänger sie weiterleiten, deduplizieren und verifizieren können:

X-Objectstack-Event:     <event type, e.g. data.record.created>
X-Objectstack-Delivery:  <delivery id — use as your idempotency key>
X-Objectstack-Attempt:   <attempt number, starting at 1>

Wenn ein Webhook-Abonnement über ein secret verfügt, signiert ObjectOS außerdem jede Anfrage:

X-Objectstack-Signature: sha256=<hex hmac>

Die Signatur ist HMAC-SHA256(secret, body), berechnet über den rohen Anfragetext. Verifizieren Sie sie auf dem Empfänger, bevor Sie der Nutzlast vertrauen:

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

function verify(body, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
  return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

Rotieren Sie Secrets, indem Sie ein neues Abonnement mit dem neuen Secret ausstellen, beide für ein Übergangsfenster betreiben und dann das alte deaktivieren.

Erwartungen an den Empfänger

• Antworten Sie innerhalb weniger Sekunden mit 2xx. Eine Antwort mit 408, 429 oder 5xx (oder ein Timeout-/Transportfehler) ist erneut versuchbar und wird mit Backoff erneut versucht. Jedes andere 4xx wird als dauerhafter Fehler behandelt und ohne weitere erneute Versuche auf dead gesetzt.
• Der Dispatcher markiert eine Zustellung erst dann als erfolgreich, wenn er ein 2xx sieht, sodass ein fehlgeschlagener Empfänger die Zeile zur Inspektion oder erneuten Zustellung in sys_webhook_delivery behält.
• Seien Sie idempotent — deduplizieren Sie anhand des X-Objectstack-Delivery-Headers (der Zustellungs-ID) oder Ihrer eigenen Ereignis-ID in der Nutzlast.

Fehlerbehandlung

Wenn etwas fehlschlägt:

1. Prüfen Sie sys_webhook_delivery auf die Zeile — status, response_code, response_body und attempts werden aufgezeichnet.
2. Bestätigen Sie den ausgehenden Netzwerkzugriff von ObjectOS zum Empfänger.
3. Wenn der Empfänger dauerhaft geändert wurde, aktualisieren Sie die Abonnement-URL und stellen Sie die Zeile aus der Console erneut zu.
4. Für die Vorfallüberprüfung erfassen Audit-Logs (sys_audit_log) Abonnementbearbeitungen, aber keine Nutzlasten — Nutzlasten verbleiben in der Outbox.

Betriebstipps

• Platzieren Sie keine Secrets in Webhook-URLs (Query-Strings werden protokolliert).
• Verwenden Sie einen dedizierten Empfänger-Hostnamen, damit Sie Last abwerfen können, indem Sie ihn am Edge blockieren, ohne die Hauptanwendung zu beeinträchtigen.
• Beobachten Sie die Dispatcher-Latenz — eine wachsende Outbox bedeutet in der Regel, dass der Empfänger beeinträchtigt ist.