# Wie wird ein Webhook zugestellt?

Ein Webhook ist eine Anfrage, die die Plattform an eine Adresse Ihrer Wahl schickt, sobald in Ihrer Organisation etwas geschieht — hier der Weg vom Ereignis bis zur Antwort Ihres Servers, und was passiert, wenn er nicht antwortet.

> **Typ:** konzept
> **Für wen:** Wer einen Empfänger für Webhooks baut oder betreibt und wissen will, womit er rechnen muss.
> **Voraussetzung:** keine zum Lesen; zum Anlegen eines Endpunkts die Rolle Inhaber und ein Paket, das Webhooks enthält (ab Premium).

## Vom Ereignis zur Zustellung

Jedes fachliche Ereignis, das im Kontext Ihrer Organisation entsteht, wird mit Ihren Webhook-Endpunkten abgeglichen. Es trifft auf jeden Endpunkt, der aktiv ist und diesen Ereignistyp abonniert hat. Der Abgleich kennt drei Formen und keine weiteren: den genauen Ereignistyp, den ganzen Bereich (`composition.*`) und `*` für alles. `composition.scene.published` erreicht damit einen Endpunkt, in dessen Liste dieser Text, `composition.*` oder `*` steht.

Für jeden passenden Endpunkt entsteht eine eigene Zustellung mit eigener Nummer (`whd_…`). Ihr Rumpf ist die Nutzlast des Ereignisses als JSON. Die Plattform signiert diesen Rumpf mit dem Geheimnis des Endpunkts (HMAC-SHA256) und schickt ihn per POST an Ihre Adresse, zusammen mit den Kopfzeilen `X-Signature`, `X-Event-Type` und `X-Delivery-Id`. Ihr Server hat zehn Sekunden Zeit. Antwortet er mit einem Status 2xx, gilt die Zustellung als zugestellt.

## Wenn der Empfänger nicht antwortet

Antwortet Ihr Server mit 5xx, 408 oder 429, oder kommt gar keine Antwort (Netzfehler, Zeitüberschreitung), wertet die Plattform das als vorübergehende Störung und wiederholt: höchstens fünf Versuche, mit Wartezeiten von 2, 4, 8 und 16 Minuten, die ein Takt alle fünf Minuten aufnimmt. Nach dem fünften Fehlschlag ist die Zustellung endgültig gescheitert. Die genauen Werte stehen im [Wiederholungsschema](/de/webhooks/delivery-and-retries#wiederholungsschema).

Jede andere 4xx-Antwort (etwa 400, 401 oder 404) gilt als Fehler auf Ihrer Seite, den eine Wiederholung nicht heilt: Die Zustellung scheitert sofort endgültig, ohne weiteren Versuch. Erneut anstoßen lässt sie sich dann nur über die API.

## Wenn ein Endpunkt dauerhaft scheitert

Jeder Fehlschlag erhöht einen Zähler am Endpunkt, jeder Erfolg setzt ihn auf null. Mehr als 20 Fehlschläge in Folge schalten den Endpunkt ab: Er wird inaktiv, erhält keine neuen Zustellungen mehr, und die Plattform verzeichnet das Ereignis `notifications.webhook.endpoint.disabled`. Ein stündlicher Lauf prüft zusätzlich, ob ein aktiver Endpunkt über der Schwelle liegt. Nach der Behebung schalten Sie ihn im Portal mit **Aktivieren** wieder ein; das wird bis zu eine Stunde später wirksam.

Zwei Sorten Ereignisse erreichen nie einen Endpunkt: die Ereignisse der Zustellung selbst (`notifications.*`), sonst löste jede Zustellung die nächste aus, und Ereignisse ohne Organisationsbezug, etwa aus dem Plattformbetrieb.

![Ablauf einer Zustellung: Ereignis, Abgleich mit den aktiven Endpunkten, Signieren, POST mit zehn Sekunden Zeitlimit, dann Zugestellt bei 2xx oder Wiederholung bei 5xx, 408, 429 und Netzfehler; andere 4xx scheitern sofort; mehr als 20 Fehlschläge in Folge schalten den Endpunkt ab](/de/webhooks/bilder/4bc6de09-delivery.svg)

## Was daraus folgt

- **Antworten Sie sofort mit 2xx und verarbeiten Sie danach.** Das Zeitlimit von zehn Sekunden gilt für die ganze Anfrage. Wer erst verarbeitet und dann antwortet, riskiert unnötige Wiederholungen.
- **Entdoppeln Sie nach `X-Delivery-Id`.** Eine Wiederholung trägt dieselbe Nummer wie der erste Versuch. Wer die Nummer speichert, verarbeitet jede Zustellung genau einmal, auch wenn seine erste Antwort unterwegs verloren ging.
- **Antworten Sie mit 4xx nur, wenn die Zustellung wirklich unbrauchbar ist.** Eine 4xx beendet die Zustellung endgültig. Ist Ihr System nur gerade nicht bereit, antworten Sie mit 503 oder 429 — dann kommt die Plattform wieder.
- **Prüfen Sie das Zustell-Log**, wenn etwas fehlt. Es zeigt je Zustellung den Zustand, den Antwortcode und die Zahl der Versuche.

## Weiterführendes

- [Was gesendet wird und wie wiederholt wird](/de/webhooks/delivery-and-retries)
- [Die Signatur einer Zustellung prüfen](/de/webhooks/verify-signature)
- [Ereignistypen: Organisation, Konten, Abrechnung](/de/webhooks/event-types-organization)