Was passiert bei Webhook-Zustellfehlern?

Ab Tarif Elite

Kurzantwort

Jede Zustellung hat 10 Sekunden Zeit; danach, oder bei Netzwerkfehlern und Nicht-2xx-Antworten, wird sie als fehlgeschlagen im Zustellprotokoll vermerkt (Status-Code bzw. Fehlertext). Einen automatischen Retry gibt es derzeit nicht: Jedes Ereignis wird genau einmal zugestellt (at-most-once). Verpasste Ereignisse holst du über das Protokoll plus API-Abgleich nach; Tests wiederholst du mit „Test senden”.

Voraussetzungen

Zustellprotokoll öffnen. Verwaltung → Webhooks → Webhook auswählen. Das Protokoll zeigt die letzten Zustellungen mit Ereignis, Erfolg, Status-Code und ggf. Fehlertext (z. B. HTTP 500 oder ein Verbindungsfehler).
Fehler einordnen. HTTP 4xx/5xx = dein Endpunkt hat geantwortet, aber nicht mit 2xx (Signaturprüfung? Bug? Wartung?). Ein Fehlertext ohne Status-Code = dein Endpunkt war gar nicht erreichbar (DNS, TLS, Timeout nach 10 s).
Erneut testen. Nach der Korrektur mit „Test senden” ein signiertes ping-Ereignis auslösen und den neuen Protokoll-Eintrag prüfen.

Das Zustellprotokoll liefert die letzten 50 Einträge, neueste zuerst:

curl -H "Authorization: Bearer inv_dein_token" \
  https://demo.notory.io/api/v1/webhooks/018f9f44-5e6f-7a77-b182-9c0d1e2f3a41/deliveries

[
  {
    "id": "018f9f50-aaaa-7bbb-cccc-1d2e3f405162",
    "webhook_id": "018f9f44-5e6f-7a77-b182-9c0d1e2f3a41",
    "event": "asset.created",
    "success": false,
    "status_code": 500,
    "error": "HTTP 500",
    "created_at": "2026-07-08T11:20:44Z"
  },
  {
    "id": "018f9f4e-bbbb-7ccc-dddd-2e3f40516273",
    "webhook_id": "018f9f44-5e6f-7a77-b182-9c0d1e2f3a41",
    "event": "ping",
    "success": true,
    "status_code": 204,
    "error": null,
    "created_at": "2026-07-08T11:05:02Z"
  }
]

Eine fehlgeschlagene Zustellung lässt sich nicht per API erneut anstoßen; nur die Testzustellung ist wiederholbar (POST /api/v1/webhooks/{id}/test). Zum Nachholen verpasster asset.created-Ereignisse eignet sich der Abgleich über die Asset-Liste:

curl -H "Authorization: Bearer inv_dein_token" \
  "https://demo.notory.io/api/v1/assets?page=1&page_size=100"
# → mit den eigenen Daten abgleichen (created_at seit dem letzten Erfolg)

Was passiert dabei?

Ablauf einer Zustellung. Ereignis tritt ein → Notory ermittelt die aktiven, abonnierten Webhooks des Mandanten → POST mit Signatur, Timeout 10 s → Ergebnis (success, status_code, error) wird als Protokoll-Eintrag gespeichert. Als Erfolg zählt ausschließlich eine 2xx-Antwort.
At-most-once, kein Backoff. Es gibt keine automatische Wiederholung, keine Warteschlange mit Backoff und keine Deaktivierung nach Fehlerserien. Jede Zustellung ist ein einzelner Versuch. Plane deinen Empfänger entsprechend: klein, schnell, hochverfügbar; schwere Arbeit asynchron dahinter.
Der Auslöser leidet nie. Zustellungen laufen nach der eigentlichen Aktion als Hintergrund-Aufgabe (best-effort). Ein toter Empfänger bremst oder verhindert also nie das Anlegen eines Assets.
Empfohlene Empfänger-Strategie. Antworte sofort mit 204 (erst annehmen, dann verarbeiten), verarbeite idempotent (z. B. anhand data.id), und gleiche nach Ausfällen den Zeitraum per API ab, statt auf erneute Zustellung zu warten.
Aufbewahrung. Das Protokoll zeigt je Webhook die letzten 50 Zustellungen. Für längerfristige Auswertung eigene Logs beim Empfänger führen.