Webhooks einrichten

Ein Webhook lässt die Plattform Ihrem System sagen, dass etwas passiert ist, statt dass Ihr System alle dreißig Sekunden nachfragt. Dieser Artikel ist der technische Vertrag, den Ihr Integrator braucht; das größere Bild — Events, Abonnements, Wiederholungen und Abgleich — steht in Events und Webhooks.

1. Die Topics aus dem Katalog wählen

Öffnen Sie Events › Event Catalog und lesen Sie, was existiert und was jedes Event trägt. Raten Sie keinen Topic-Namen.

Topics sind kleingeschrieben und punktgetrennt, in einer von zwei Formen:

Abonnieren Sie eng. Ein Empfänger, der alles abonniert hat, verarbeitet eines Tages ein Event, das er hätte ignorieren sollen — und er ist auch der Empfänger, der umfällt, wenn jemand eine Massenbearbeitung über 30.000 Produkte fährt.

2. Das Ziel anlegen

Gehen Sie zu Webhooks › Outbound und wählen Sie New webhook. Vier Felder:

Prüfen Sie danach die Detailseite: Sie zeigt den Endpoint, die Subscribed topics, das Signing secret — dort steht unsigned, wenn Sie es leer gelassen haben — und den Status.

3. Wie eine Zustellung aussieht

Eine Zustellung ist ein HTTP-POST mit JSON-Body und vier Headern:

POST /hooks/orders HTTP/1.1
Content-Type: application/json
X-Revenexx-Id: evt_01jc8m4yq2…
X-Revenexx-Topic: order.created
X-Revenexx-Timestamp: 1748685600
X-Revenexx-Signature: v0=9f86d081884c7d659a2feaa0c55ad015a…

Der Body trägt einen konsistenten Umschlag:

{
  "tenant_id": "acme-eu",
  "topic": "order.created",
  "id": "evt_01jc8m4yq2…",
  "data": { "order_id": "o_8421", "total": 14990, "currency": "EUR" },
  "metadata": { "source": "checkout" },
  "time": "2026-05-31T10:00:00Z"
}

Zwei Eigenschaften von id sind für den Autor des Empfängers wichtig: Sie ist eindeutig je Event, und sie ist über Wiederholungen hinweg stabil. Sie ist damit der Deduplizierungsschlüssel, und sie ist der einzige richtige.

4. Die Signatur prüfen

Diesen Teil lohnt es, exakt richtig zu machen.

Die Aufgabe des Empfängers, in dieser Reihenfolge:

1. Die rohen Bytes des Bodys nehmen — vor jedem JSON-Parsing, bevor irgendein Framework ihn neu serialisiert. Ein dekodierter und neu kodierter Body stimmt nicht überein, und das ist die mit Abstand häufigste Ursache von „die Signatur ist immer falsch".
2. HMAC-SHA256 über diese Bytes mit dem Signing-Secret berechnen.
3. In konstanter Zeit vergleichen, gegen den Hex-Wert nach v0=. Ein gewöhnlicher String-Vergleich verrät Timing-Information; jede Sprache hat einen Constant-Time-Vergleich.
4. Mehrere Signaturen behandeln. Während einer Secret-Rotation kann der Header mehr als eine kommagetrennte Signatur tragen. Die Zustellung gilt als gültig, wenn eine davon passt — das macht Rotation ohne Downtime möglich.
5. Alles, was nicht verifiziert, mit 401 ablehnen und nicht verarbeiten.

Prüfen Sie zusätzlich den Zeitstempel. Eine Zustellung, deren X-Revenexx-Timestamp weit von Ihrer eigenen Uhr entfernt liegt — mehr als ein paar Minuten in beide Richtungen —, sollte abgewiesen werden; das verhindert, dass eine alte mitgeschnittene Zustellung später gegen Sie abgespielt wird. Dieselbe Prüfung ist auch der Grund, warum ein Empfänger mit driftender Uhr einwandfreie Zustellungen ablehnt; siehe Häufige API-Probleme.

5. Regeln für den Empfänger

Bestehen Sie schriftlich darauf, denn den Code kontrollieren meist nicht Sie:

• Schnell antworten, später verarbeiten. Body annehmen, 2xx zurückgeben, die ERP-Arbeit danach erledigen. Ein Empfänger, der vor der Antwort fünf Sekunden arbeitet, läuft unter Last in Timeouts und provoziert Wiederholungen, die die Last verschärfen.
• Auf X-Revenexx-Id deduplizieren. Zustellung ist at-least-once, dasselbe Event wird irgendwann zweimal ankommen. Eine Wiederholung muss ein No-op sein.
• Nicht auf die Ankunftsreihenfolge bauen. Zwei Events im Sekundenabstand können in beliebiger Reihenfolge ankommen. Zählt die Abfolge, lesen Sie time aus dem Umschlag.
• Unbekannte Felder ignorieren. Neue optionale Felder erscheinen innerhalb eines Topics ohne Ankündigung; ein Empfänger, der daran scheitert, bricht an einem gewöhnlichen Dienstag.

6. Eine Testzustellung senden und das Protokoll lesen

Lösen Sie eine Testzustellung aus und prüfen Sie, dass der Empfänger 2xx antwortet. Öffnen Sie dann die Delivery attempts des Webhooks — jede Zeile zeigt das Event, die Versuchsnummer (Try), den Status, den HTTP-Code und When.

Worauf Sie achten:

• Der erste Versuch war erfolgreich. Wiederholungen schon bei der allerersten Zustellung heißen: Der Empfänger ist langsam, und an Ihrem vollsten Tag wird er langsamer sein.
• Die Antwortzeit liegt deutlich innerhalb des Timeouts Ihres Empfängers.
• Eine absichtlich verfälschte Signatur wird mit 401 abgelehnt. Testen Sie das. Ein Endpoint, der eine falsche Signatur akzeptiert, ist schlimmer als gar keine Signatur, weil alle ihn für geschützt halten.

Inbound: die andere Richtung

Ein externes System kann auch in die Plattform hineinschieben. Inbound-Endpoints haben eine eigene Adresse der Form https://webhooks.revenexx.com/in/<endpoint-id>, mit langer, nicht erratbarer Id, und werden unter Webhooks › Inbound verwaltet.

Drei Antworten, mit denen zu rechnen ist — und über die Sie den Absender informieren:

Anders als Outbound-Ziele wird ein Inbound-Endpoint bei fehlschlagenden Zustellungen nicht automatisch deaktiviert — den Absender für ein Problem auf Ihrer Seite zu bestrafen wäre das falsche Verhalten.

Was Sie prüfen

• Ein echtes Event hat eine Zustellung erzeugt, und der Empfänger hat sie einmal verarbeitet.
• Dasselbe Event, erneut abgespielt, hat keine zweite Bestellung erzeugt.
• Eine falsche Signatur wird abgelehnt.
• Das Zustellprotokoll ist sauber — kein wachsender Schwanz an Wiederholungen.

Weiter

• Eine Integration durchgängig testen — Replay, Idempotenz und die Go-live-Checkliste.
• Integrationen überwachen — Zustellungen im Blick behalten, sobald sie live sind.