Was gesendet wird und wie wiederholt wird

Die Anfrage, die Ihr Endpunkt bekommt, die Zustände einer Zustellung, das Wiederholungsschema und die Abschaltung — zum Nachschlagen beim Bau und beim Betrieb eines Empfängers.

Die Anfrage an Ihren Endpunkt#

Jede Zustellung ist ein POST an die Adresse des Endpunkts. Der Rumpf ist die Nutzlast des Ereignisses als JSON, kompakt serialisiert (ohne Leerzeichen und Zeilenumbrüche). Nur die Nutzlast reist; der Zeitpunkt des Ereignisses, seine Kennung und der Auslöser stehen nicht im Rumpf.

So sieht eine Zustellung des Ereignisses composition.scene.published aus (Rumpf zur Lesbarkeit umgebrochen; tatsächlich kommt er in einer Zeile):

POST /hooks/signage HTTP/1.1
Host: warenwirtschaft.example.com
Content-Type: application/json
X-Signature: 3q2-7wE5c1nXm0Zk8YbT4vLpQ9sRd6HfJgUaWi2xO7A
X-Event-Type: composition.scene.published
X-Delivery-Id: whd_01KXZACW98SENDNG0000000001

{
  "sceneId": "scn_01KJPX8NH0SZENE00000000001",
  "tenantId": "tnt_01KERPXZM0ADERAPTHEKE00001",
  "sceneVersionId": "scv_01KV5K0JE0VERSN00000000003",
  "versionNumber": 4,
  "contentHash": "b2f80a41d76c395ee0138b5a4c9d27f6103e8ab7592c4df081a63be95d7c024f",
  "appVersionPins": {},
  "publishedById": "usr_01KFB7QPW0TEAM000000000002",
  "at": "2026-07-20T08:31:05.000Z"
}

Die erwartete Antwort#

Bei einem Fehlschlag wird der Antworttext gekürzt (höchstens 4 kB) im Zustell-Log gespeichert; bei einer erfolgreichen Zustellung wird nur der Statuscode festgehalten. Ein kurzer, sprechender Text hilft Ihnen später beim Nachsehen; nötig ist er nicht.

Zustände einer Zustellung#

Der Weg ist pending → delivered oder failed; aus failed führt jeder weitere Versuch wieder über pending nach delivered, failed oder dead. Für den Zustand dead führt das Portal keine eigene Beschriftung; das Zustell-Log zeigt dort den Wert selbst. Die Beschriftung Wiederholung läuft ist im Portal angelegt, aber keinem Zustand zugeordnet.

Wiederholungsschema#

Die Plattform wiederholt nur bei 5xx, 408, 429, Zeitüberschreitung und Netzfehlern. Je Zustellung gibt es höchstens fünf Versuche. Die Wartezeit nach dem n-ten Fehlschlag beträgt 1 Minute · 2ⁿ, mit ±20 % Streuung. Fällige Wiederholungen nimmt ein Takt alle fünf Minuten auf, bis zu 100 je Lauf — die tatsächliche Wartezeit ist deshalb bis zu fünf Minuten länger als der Sollwert.

Eine 4xx-Antwort außer 408 und 429 beendet die Zustellung sofort, unabhängig vom Versuchszähler.

Erneut zustellen von Hand#

Im Zustell-Log des Endpunkts steht an jeder Zustellung mit Status Fehlgeschlagen die Schaltfläche Erneut zustellen. Für eine Zustellung im Zustand dead zeigt das Portal keine Schaltfläche; sie stoßen Sie über die API an:

curl -X POST "$SZENERA_API/v1/webhooks/whk_01KPR20K40WEBHK00000000001/deliveries/whd_01KXZACW98SENDNG0000000001/retry" \
  -H "Authorization: Bearer $TOKEN"

Die Antwort (Status 201) ist die Zustellung mit dem Ausgang des neuen Versuchs. Der neue Versuch wird mit dem aktuell gültigen Geheimnis des Endpunkts signiert und trägt dieselbe X-Delivery-Id. Ist der Endpunkt inaktiv, wird nichts gesendet; die Antwort trägt die Zustellung unverändert. Die API prüft den Zustand nicht: Auch eine bereits zugestellte Zustellung lässt sich so erneut senden — Ihr Empfänger sieht dann dieselbe Nummer ein zweites Mal.

Abschaltung eines Endpunkts#

Jeder Fehlschlag erhöht den Zähler consecutiveFailures des Endpunkts, jeder Erfolg setzt ihn auf null. Liegt der Zähler über 20, wird der Endpunkt inaktiv (active: false), und die Plattform verzeichnet notifications.webhook.endpoint.disabled. Ein stündlicher Lauf holt nach, was der Zähler beim Versand verfehlt hat. Ein inaktiver Endpunkt bekommt keine neuen Zustellungen; im Portal steht er auf Inaktiv mit dem Hinweis „letzter Fehler …“. Wieder einschalten: Aktivieren oder PATCH /v1/webhooks/{id} mit {"active": true}. Das wirkt nicht sofort: Die Plattform merkt sich je Ereignistyp bis zu eine Stunde, ob ein aktiver Endpunkt ihn abonniert. Nach dem Aktivieren oder nach dem Ergänzen von Ereignissen kann es deshalb bis zu eine Stunde dauern, bis die erste Zustellung eines neu abonnierten Typs ankommt; neu angelegte Endpunkte sind sofort wirksam.

Das Zustell-Log über die API#

curl "$SZENERA_API/v1/webhooks/whk_01KPR20K40WEBHK00000000001/deliveries?limit=50" \
  -H "Authorization: Bearer $TOKEN"

Die Antwort ist eine Seite mit items und nextCursor (wenn es weitergeht). Der nächste Aufruf bekommt cursor=<nextCursor>; limit liegt zwischen 1 und 200, ohne Angabe bei 50.

{
  "items": [
    {
      "id": "whd_01KXZACW98SENDNG0000000001",
      "tenantId": "tnt_01KERPXZM0ADERAPTHEKE00001",
      "endpointId": "whk_01KPR20K40WEBHK00000000001",
      "eventType": "composition.scene.published",
      "payloadSignature": "3q2-7wE5c1nXm0Zk8YbT4vLpQ9sRd6HfJgUaWi2xO7A",
      "status": "delivered",
      "attemptCount": 1,
      "responseCode": 200,
      "responseBody": null,
      "nextRetryAt": null,
      "dispatchedAt": "2026-07-20T08:31:05.000Z",
      "deliveredAt": "2026-07-20T08:31:06.000Z",
      "deadAt": null,
      "createdAt": "2026-07-20T08:31:05.000Z"
    }
  ],
  "nextCursor": "d2hkOjIwMjYtMDctMTk"
}

Der gesendete Rumpf selbst steht nicht in der Liste.

Rechte#

Diese Rechte gelten für angemeldete Konten. Ein API-Schlüssel (ak_…) kann sie nicht tragen; die Aufrufe brauchen das Zugriffstoken einer Anmeldung, siehe Anmeldung.

Weiterführendes#

• Wie wird ein Webhook zugestellt?
• Die Signatur einer Zustellung prüfen
• Wenn keine Zustellung ankommt