Zustellungen und Wiederholungen

Eine Zustellung ist ein Ereignis, das an einen Webhook gesendet wird. Diese Seite beschreibt, wie die Anfrage einer Zustellung aussieht, wann sie als erfolgreich gilt, wie fehlgeschlagene Zustellungen wiederholt werden und was geschieht, wenn Zustellungen an einen Endpunkt dauerhaft fehlschlagen.

Die Anfrage

POST /beepclock/webhooks HTTP/1.1
Host: integration.example.com
Content-Type: application/json; charset=utf-8
User-Agent: BeepClock-Webhooks/1.0
X-BeepClock-Webhook-Id: c5d8a2e7-4b19-4f63-8a0d-3e7b9c1f6a52
X-BeepClock-Event: timeEntry.created
X-BeepClock-Delivery: 8f2c6a1d-4e7b-5c93-a0d5-1b8e3f6c9a24
X-BeepClock-Attempt: 1
X-BeepClock-Signature: t=1791788292,v1=5d1f…c2a8

{"id":"8f2c6a1d-4e7b-5c93-a0d5-1b8e3f6c9a24","event":"timeEntry.created",…}

Der Anfragetext ist der Ereignisumschlag als kompaktes JSON.

Header

Header	Beschreibung
X-BeepClock-Webhook-Id	Kennung des Webhooks, zu dem die Zustellung gehört.
X-BeepClock-Event	Ereignistyp, zum Beispiel timeEntry.created. Siehe die Ereignisreferenz.
X-BeepClock-Delivery	Kennung der Zustellung, der Idempotenzschlüssel. Entspricht dem Feld id im Umschlag.
X-BeepClock-Attempt	Nummer des Versuchs, beginnend bei 1.
X-BeepClock-Signature	HMAC-Signatur. Siehe Signaturen prüfen.

Für den Webhook konfigurierte eigene Header, zum Beispiel Authorization, werden jeder Anfrage hinzugefügt, auch Testereignissen. Ihre Namen dürfen nicht mit X-BeepClock- beginnen und keine Transport-Header wie Content-Type, Host oder User-Agent ersetzen. Ihre Werte dürfen nur druckbare ASCII-Zeichen enthalten.

Transport

Eigenschaft	Regel
Methode	POST
URL	Nur https, absolut, höchstens 2048 Zeichen, ohne user:password@.
Zielhost	Muss öffentlich erreichbar sein. Loopback-, private, Link-Local-, Carrier-Grade-NAT-, Dokumentations-, Multicast- und reservierte Adressen werden in IPv4 und IPv6 blockiert. Die Prüfung erfolgt beim Speichern der URL und erneut bei jeder Verbindung nach der DNS-Auflösung.
Timeout	10 Sekunden.
Weiterleitungen	Werden nicht verfolgt. Eine 3xx-Antwort gilt als Fehlschlag.
Erfolg	Jeder 2xx-Statuscode. Alles andere, einschließlich Timeouts sowie Verbindungs- und TLS-Fehlern, gilt als Fehlschlag.
Antworttext	Wird ignoriert.

Wiederholungsplan

Schlägt ein Versuch fehl, wiederholt BeepClock die Zustellung nach einem festen Zeitplan:

Versuch	Verzögerung nach dem vorherigen Versuch
1	sofort
2	1 Minute
3	5 Minuten
4	30 Minuten
5	2 Stunden
6	8 Stunden
7	24 Stunden

Eine Zustellung hat höchstens 7 automatische Versuche, verteilt auf etwa 35 Stunden. Nach dem letzten fehlgeschlagenen Versuch wird die Zustellung als fehlgeschlagen markiert. Sobald der Endpunkt wieder funktioniert, können Sie sie dennoch erneut senden.

Automatisches Pausieren

BeepClock pausiert einen Webhook automatisch, wenn:

• der Endpunkt mit 410 Gone antwortet. Die Zustellung wird nicht wiederholt und der Webhook sofort pausiert. Geben Sie 410 nur zurück, wenn der Endpunkt dauerhaft stillgelegt ist.
• 20 Zustellungen in Folge fehlgeschlagen sind. Eine Zustellung zählt einmal, nachdem alle ihre Versuche fehlgeschlagen sind, und jede erfolgreiche Zustellung setzt den Zähler zurück.

Wird ein Webhook automatisch pausiert, sendet BeepClock den Benutzern des Kontos eine E-Mail mit dem Grund und einem Link zum Webhook. Die Webhook-Liste zeigt den Grund im Status an.

Solange ein Webhook pausiert ist, automatisch oder über Senden pausieren:

• werden Zustellungen, die auf eine Wiederholung warten, nicht gesendet. Sie werden mit dem Fehler Webhook is disabled or deleted. als fehlgeschlagen markiert;
• werden Ereignisse, die während der Pause eintreten, nicht nachträglich zugestellt. Nach Senden fortsetzen werden nur neue Ereignisse gesendet.

Zustellprotokoll

Die Seite des Webhooks zeigt jede Zustellung der letzten 30 Tage, die neuesten zuerst, und lässt sich nach Status filtern. Wählen Sie eine Zustellung aus, um Folgendes zu sehen:

• jeden Versuch mit HTTP-Statuscode, Dauer und Fehler;
• den genau gesendeten Payload;
• wann der nächste Versuch geplant ist, falls die Zustellung noch aussteht.

Zustellung erneut senden

Erneut senden in den Zustelldetails sendet die Zustellung noch einmal mit derselben Zustell-ID und demselben Anfragetext. Die Versuchsnummer setzt die bisherigen Versuche fort: Eine im ersten Versuch erfolgreiche Zustellung wird als Versuch 2 erneut gesendet.

Erneutes Senden ist möglich, wenn der Webhook aktiv ist und die Zustellung nicht mehr aussteht. Eine Zustellung, die mehr als eine Stunde nach ihrem geplanten Versuch noch aussteht, zum Beispiel nach einem unterbrochenen Senden, kann ebenfalls erneut gesendet werden.

Schlägt ein erneut gesendeter Versuch fehl, wird der automatische Wiederholungsplan ab dieser Versuchsnummer fortgesetzt; ab Versuch 7 gibt es keine weiteren automatischen Wiederholungen. Eine erneut gesendete Zustellung zählt für das automatische Pausieren wie jede andere Zustellung.

Testereignisse

Testereignis senden sendet sofort ein signiertes Ereignis webhook.test mit dem aktuellen Geheimnis und den eigenen Headern und zeigt die Antwort an. Ein Testereignis:

• hat jedes Mal eine neue, zufällige Zustell-ID und X-BeepClock-Attempt: 1;
• wird einmal gesendet und nie wiederholt;
• wird nicht ins Zustellprotokoll aufgenommen und zählt nicht für das automatische Pausieren;
• kann auch bei pausiertem Webhook gesendet werden, um den Endpunkt vor dem Fortsetzen zu prüfen.

Idempotenz und Reihenfolge

Die Zustellung erfolgt mindestens einmal (at-least-once): Dasselbe Ereignis kann Ihren Endpunkt mehr als einmal erreichen, zum Beispiel wenn Ihre 2xx-Antwort auf dem Rückweg verloren geht.

• Die Zustell-ID (X-BeepClock-Delivery, entspricht der id im Umschlag) ist für jedes Paar aus Webhook und Quellereignis deterministisch. Automatische Wiederholungen und manuelles erneutes Senden tragen dieselbe ID und denselben Anfragetext; nur X-BeepClock-Attempt, t und die Signatur ändern sich.
• Speichern Sie die IDs, die Sie verarbeitet haben, und behandeln Sie eine wiederholte Zustellung als unschädlich.
• Die Ankunftsreihenfolge ist nicht garantiert. Durch eine Wiederholung kann ein älteres Ereignis nach einem neueren eintreffen. Verwenden Sie occurredAt, um Ereignisse zum selben Objekt zu ordnen.