Webhook-Referenz

Verfügbare Webhook-Ziele

Heute werden drei ausgehende Webhook-Oberflächen angeboten:

Gemeinsamer Envelope

Jede Webhook-Zustellung verwendet einen gemeinsamen JSON-Envelope:

{
  "event_id": "evt_01HZQX...",
  "event_type": "scheduled_export.completed",
  "tenant_id": "acme-logistics",
  "timestamp": "2026-05-09T14:32:08Z",
  "delivery_attempt": 1,
  "data": { ... event-specific payload ... }
}

Die event_id ist pro logischem Ereignis eindeutig — verarbeiten Sie idempotent über diese ID, da Retries dieselbe ID mit einem inkrementierten delivery_attempt zustellen.

Signaturverifizierung

Jede Webhook-Zustellung enthält einen X-PulseCargo-Signature-Header mit einer HMAC-SHA256-Signatur, berechnet über den Request-Body mit dem Webhook-Signing-Secret Ihres Mandanten.

Verifizierung in Pseudocode:

signature = HMAC-SHA256(your_signing_secret, request.body)
expected  = request.headers["X-PulseCargo-Signature"]
constant_time_equal(signature, expected)  // muss Constant-Time-Vergleich verwenden

Lehnen Sie jeden Request ab, bei dem die Signatur nicht übereinstimmt. Das Signing-Secret ist rotierbar; die Rotation wird 30 Tage im Voraus über die Admin-Oberfläche kommuniziert.

Retry-Richtlinie

Wenn Ihr Endpunkt einen Nicht-2xx-Statuscode zurückgibt (oder nicht innerhalb von 10 Sekunden antwortet), versucht PulseCargo es mit exponentiellem Backoff erneut:

• Versuch 1 — sofort
• Versuch 2 — 1 Minute später
• Versuch 3 — 5 Minuten später
• Versuch 4 — 30 Minuten später
• Versuch 5 — 2 Stunden später
• Versuch 6 — 12 Stunden später
• Versuch 7 (final) — 24 Stunden später

Nach dem siebten fehlgeschlagenen Versuch wird das Ereignis dauerhaft als fehlgeschlagen markiert und im Webhook-Health-Dashboard des Mandanten angezeigt. Die ursprüngliche event_id bleibt erhalten, sodass ein manuelles erneutes Senden (nachdem Sie den empfangenden Endpunkt repariert haben) sauber abgeglichen wird.

Empfänger-Anforderungen

• Schnell antworten. Geben Sie innerhalb von 10 Sekunden 2xx zurück. Verarbeiten Sie das Payload bei Bedarf asynchron.
• Idempotenz. Schlüssel auf event_id. Behandeln Sie wiederholte Zustellungen als No-Ops nach der ersten erfolgreichen Verarbeitung.
• Signatur verifizieren. Lehnen Sie Requests ohne gültige Signatur ab.
• HTTPS verwenden. HTTP-Endpunkte sind für Produktions-Webhooks nicht zulässig.
• Unseren IP-Bereich zulassen. Wenn Ihr Endpunkt durch eine Firewall geschützt ist, erlauben Sie PulseCargos ausgehenden IP-Bereich (in der Admin-Oberfläche bereitgestellt), Sie zu erreichen.

Health-Monitoring

Mandanten-Administratoren können den Webhook-Zustellungs-Health unter Admin → Integrations → Webhooks einsehen: Erfolgsrate pro Ziel, letzte erfolgreiche Zustellung, aktuell wiederholte Events, dauerhaft fehlgeschlagene Events mit Replay-Buttons.

Dauerhaft fehlgeschlagene Events werden 90 Tage für Replay aufbewahrt; ältere fehlgeschlagene Events werden gelöscht.

Sicherheit und Audit

Jede ausgehende Webhook-Zustellung wird in OutboundApiTraffic mit Zeitstempel, Ziel-URL, Antwortstatus und Zustellungsversuch protokolliert. Mandanten-Administratoren können das Log nach Compliance-Nachweisen abfragen.

Signing-Secret-Rotation, Änderungen der Ziel-URL und Webhook-On/Off-Umschaltungen werden alle Audit-protokolliert. SOC 2 Evidence Collection.