Webhooks
Die wichtigsten Befehle zum Merken
curl --data …— einen HTTP-POST-Payload senden.curl -i— Status und Antwortheader des Empfängers prüfen.
Befehle und Optionen
| Option oder Argument | Bedeutung |
|---|---|
--data '{…}' |
Den zitierten JSON-Body mit POST senden. |
-H 'Content-Type: application/json' |
JSON als Format angeben. |
-H 'X-Lab-Event-ID: lab-1' |
Eine eigene Testkennung senden, keine standardisierte Providersignatur. |
-i --max-time 5 |
Header zeigen und auf fünf Sekunden begrenzen. |
Beide Befehle verwenden absichtlich dieselbe ID. Anführungszeichen erhalten JSON und Header.
Die entscheidenden Konzepte
1. Ein Webhook ist ein HTTP-Rückruf
Ein Webhook sendet ein Ereignis vom Anbieter an einen konfigurierten HTTP-Endpunkt des Empfängers. Dieser erhält Benachrichtigungen, statt ständig nach Änderungen zu fragen.
Der Endpunkt ist eine API mit Eingabeprüfung, Größenlimits und einem Antwortvertrag. Ein eingehendes JSON-Dokument ist nicht automatisch vertrauenswürdig, selbst wenn es einem echten Provider-Payload ähnelt.
2. Echtheit muss vor der Aktion geprüft werden
Anbieter signieren häufig Payloads oder verwenden andere Authentifizierung. Die Prüfung muss genau ihrem Verfahren folgen, oft mit ursprünglichem Rohbody und Zeitstempel. JSON vor der Prüfung neu zu formatieren kann die signierten Bytes verändern.
HTTPS schützt die Verbindung. Signaturen helfen bei Herkunft und Integrität. Bekannte Header oder Ereignis-IDs beweisen keine Echtheit. Replay-Schutz und Geheimnisrotation gehören ebenfalls zum Empfängerdesign.
3. Zustellungen können sich wiederholen oder umordnen
Ein Sender kann nach Timeout erneut senden, obwohl der Empfänger bereits fertig war und nur dessen Bestätigung verloren ging. Ereignisse müssen nicht in fachlicher Entstehungsreihenfolge eintreffen.
Verwende verfügbare stabile IDs und dauerhafte Duplikatbehandlung. Seiteneffekt und Verarbeitungsnachweis müssen so koordiniert sein, dass ein Absturz keinen irreführenden Zustand hinterlässt. Nur im Prozessspeicher gemerkte IDs verschwinden beim Neustart.
4. Die Bestätigung definiert eine Verantwortungsgrenze
Eine erfolgreiche HTTP-Antwort kann Verantwortungsübernahme bedeuten, nicht abgeschlossene Folgearbeit. Häufig wird validiert, dauerhaft eingereiht und dann bestätigt; Worker erledigen längere Verarbeitung später.
Bestätigung vor dauerhafter Annahme riskiert Verlust nach Absturz. Warten auf langsame Folgearbeit kann unnötige Wiederzustellung auslösen. Antwortvertrag und interne Dauerhaftigkeit müssen zusammenpassen.
Ein kleines Beispiel
Optional: Verwende ausschließlich den beschriebenen entbehrlichen lokalen Empfänger. Das sind Testzustellungen ohne echte Providersignatur.
curl -i --max-time 5 -H 'Content-Type: application/json' -H 'X-Lab-Event-ID: lab-1' --data '{"type":"lab.ping"}' http://127.0.0.1:8080/webhook
curl -i --max-time 5 -H 'Content-Type: application/json' -H 'X-Lab-Event-ID: lab-1' --data '{"type":"lab.ping"}' http://127.0.0.1:8080/webhookVergleiche Antworten und lokale Logs. Die ID bleibt lab-1; ein entsprechend implementierter Empfänger sollte den Effekt nicht doppelt ausführen. Gleiche 2xx-Antworten beweisen das nicht. Prüfe Effekt oder Verarbeitungsnachweis.
Ein produktiver Empfänger mit Signaturpflicht sollte diesen unsignierten Test nicht als authentisch behandeln. Connection Refused bedeutet fehlendes Lab; 4xx kann einen unpassenden Payload oder Header anzeigen.
Du wiederholst manuell und prüfst keinen Sender-Retrymechanismus. Der Empfänger kann den Testnachweis behalten. Verwende für einen frischen Lauf sein übliches Lab-Resetverfahren.
Merke dir: Authentifiziere Ereignisse, behandle Wiederzustellung sicher und bestätige an einer klaren dauerhaften Grenze.