Skip to main content

Sprachhinweis

Diese deutsche Variante ist eine gekürzte Übersetzung: Der Abschnitt „Step 6 — Move to an event sink when you outgrow HTTP receivers” existiert nur in der englischen Fassung: /en/guides/first-webhook-quickstart. Code-Blöcke, Endpoint-Pfade, API-Feldnamen und Fehlercodes bleiben englisch.

Quickstart: Ihren ersten Webhook empfangen

Drei Zustellflächen bringen Orbit-Ereignisse von der Plattform; dieses Guide hilft bei der Wahl und geht dann die vollständige Schleife des registrierten Endpunkts durch — Tunnel, Registrierung, Verifikation, Replay.

Step 1 — Zustellfläche wählen

Starten Sie mit dem Tester, solange Sie experimentieren. Wechseln Sie zu einem registrierten Endpunkt, sobald die Integration real wird — der Tester kann Requests nicht signieren und übt Ihre Verifikationslogik nie aus.

Step 2 — Lokalen Endpunkt mit einem Tunnel erreichbar machen

Kopieren Sie die HTTPS-Forwarding-URL — das ist die Adresse, die Sie im nächsten Schritt registrieren. Lassen Sie den Tunnel laufen, während Sie Registrierung und Replay durchgehen.

Step 3 — Endpunkt in der Konsole registrieren (oder über die API)

Gehen Sie im Dashboard zu Developer → Webhooks → Add endpoint. Fügen Sie Ihre Tunnel-URL ein, abonnieren Sie ein oder zwei Ereignistypen und speichern Sie. Die Konsole zeigt das Klartext-Signing-Secret (whsec_...) genau einmal — kopieren Sie es jetzt in eine Umgebungsvariable.
Die Antwort trägt Ihre Endpunkt-ID (wh_...) und das einmalige Klartext-Secret (whsec_...) — persistieren Sie es jetzt, denn jeder spätere GET auf den Endpunkt liefert nur noch einen maskierten Wert. Schmale events-Listen halten den Testverkehr übersichtlich; * ist eine Produktionsentscheidung, keine Entwicklungentscheidung.

Step 4 — Signatur empfangen und prüfen

Registrierte Zustellungen treffen signiert ein, mit einem X-Orbit-Signature-Header im Format t=<unix>,v1=<hex>. Ihr Receiver muss HMAC_SHA256(secret, "<t>.<raw body>") über die rohen Request-Bytes prüfen — bevor eine JSON-Middleware sie parsed — und Zeitstempel älter als 5 Minuten verwerfen. Ein minimaler Node-Check:
Antworten Sie mit 2xx innerhalb des 30-Sekunden-Fensters und deduplizieren Sie über die Envelope-id — Retries und Replays liefern dieselbe ID erneut. Der vollständige Vertrag (Retry-Zeitplan, Dead-Letter-Queue) steht im Webhooks overview.

Step 5 — Zustellungen aus der Konsole erneut senden

Jeder Zustellversuch ist unter Developer → Webhooks → Events einsehbar — wählen Sie eine Zeile, um Payload und die Antwort Ihres Servers zu sehen. Eine fehlgeschlagene Zustellung lässt sich mit Replay auf der Zeile erneut senden, damit Sie Ihren Receiver reparieren und dasselbe signierte Ereignis erneut feuern können, ohne neuen Verkehr auszulösen. Zustellungen, die den Retry-Zeitplan erschöpfen, landen in der Dead-Letter-Queue unter Developer → Webhooks → Dead-letter queue und sind 7 Tage lang replaybar.

Siehe auch