Wie wird ein Webhook zugestellt?
Vom Ereignis über den Abgleich mit Ihren Endpunkten, die Signatur und den Versand bis zu Wiederholung oder Abschaltung.
3 Minuten LesezeitWebhooksStand: 25.10.2026
Auf dieser Seite
Bevor Sie loslegen
- 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).
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.
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.
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.
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.