Best Practices für Empfänger

Mit diesen Empfehlungen bauen Sie einen Endpunkt, der keine Ereignisse verpasst, keine Ereignisse doppelt verarbeitet und sich nicht durch gefälschte Anfragen täuschen lässt.

Schnell antworten, später verarbeiten

BeepClock wartet höchstens 10 Sekunden auf eine Antwort. Speichern Sie das Ereignis, antworten Sie mit 2xx (zum Beispiel 202 oder 204) und erledigen Sie die eigentliche Arbeit im Hintergrund, zum Beispiel über eine Warteschlange. Aufwendige Verarbeitung innerhalb der Anfrage riskiert ein Timeout, und jedes Timeout löst eine Wiederholung eines Ereignisses aus, das Sie möglicherweise bereits verarbeitet haben.

Jede Anfrage prüfen

Prüfen Sie die Signatur auf dem unveränderten Anfragetext, bevor Sie den Payload parsen oder ihm vertrauen, vergleichen Sie Signaturen in konstanter Zeit und lehnen Sie Anfragen mit veraltetem t ab. Akzeptieren Sie jeden v1-Wert im Header, damit eine Rotation des Geheimnisses die Zustellungen nicht unterbricht.

Duplikate behandeln

Die Zustellung erfolgt mindestens einmal. Speichern Sie die Zustell-IDs, die Sie verarbeitet haben, zum Beispiel in einer Tabelle mit eindeutigem Schlüssel, und überspringen Sie eine Zustellung, deren ID Sie bereits kennen. Wiederholungen und erneutes Senden verwenden immer dieselbe ID und denselben Anfragetext.

Nicht auf die Reihenfolge verlassen

Ereignisse können in anderer Reihenfolge eintreffen, besonders nach Wiederholungen. Wenn die Reihenfolge wichtig ist, zum Beispiel wenn ein Mitarbeiter zweimal geändert wird, vergleichen Sie occurredAt und behalten Sie den neuesten Zustand.

Tolerant mit dem Payload umgehen

Ignorieren Sie unbekannte Felder und behandeln Sie fehlende Felder als null. BeepClock kann neue Felder hinzufügen, ohne apiVersion zu ändern. Bezieht sich ein Ereignis auf ein Objekt, das inzwischen gelöscht wurde, enthält data nur id.

Passende Statuscodes verwenden

Situation	Antwort
Ereignis gespeichert	Beliebiger 2xx-Status
Ungültige oder fehlende Signatur	401
Vorübergehendes Problem auf Ihrer Seite	5xx, oder lassen Sie die Anfrage in ein Timeout laufen. BeepClock wiederholt die Zustellung.
Der Endpunkt ist dauerhaft stillgelegt	410 Gone. BeepClock pausiert den Webhook sofort.

Antworten Sie nicht mit einer Weiterleitung: BeepClock folgt keinen Weiterleitungen und wertet sie als Fehlschlag.

Geheimnisse geheim halten

• Speichern Sie das Signaturgeheimnis und alle Werte eigener Header, zum Beispiel ein API-Token, in Ihrem Secret Store oder in Umgebungsvariablen, nicht im Quellcode.
• Erzeugen Sie ein neues Signaturgeheimnis, wenn das alte offengelegt worden sein könnte.
• Verwenden Sie HTTPS mit einem gültigen Zertifikat. BeepClock sendet nur an https-Adressen.

Integration überwachen

• Prüfen Sie das Zustellprotokoll nach Änderungen an Ihrem Endpunkt und verwenden Sie nach jedem Deployment Testereignis senden.
• Stellen Sie sicher, dass die E-Mail, die BeepClock beim Pausieren eines Webhooks sendet, jemanden erreicht, der darauf reagieren kann.
• Senden Sie nach der Behebung eines Ausfalls die fehlgeschlagenen Zustellungen erneut.

Checkliste

• https-Endpunkt, öffentlich erreichbar, antwortet innerhalb von 10 Sekunden mit 2xx.
• X-BeepClock-Signature wird auf dem unveränderten Anfragetext mit einem Vergleich in konstanter Zeit geprüft; der Schlüssel ist das gesamte whsec_…-Geheimnis.
• Anfragen mit veraltetem t werden abgelehnt (zum Beispiel nach 5 Minuten).
• Mehrere v1-Werte werden akzeptiert, für die Rotation des Geheimnisses.
• Zustellungen werden anhand von X-BeepClock-Delivery dedupliziert; die Verarbeitung ist idempotent.
• Keine Annahmen über die Zustellreihenfolge; occurredAt wird verwendet, wo die Reihenfolge wichtig ist.
• Unbekannte Felder werden ignoriert; fehlende Felder gelten als null.
• Schnelles 2xx und Verarbeitung im Hintergrund; 410 nur bei dauerhaft stillgelegtem Endpunkt.