Events und Webhooks

Manches darf nicht bis heute Nacht warten. Eine Bestellung muss jetzt ins ERP, ein Lager muss jetzt von einer Sendung erfahren, und ein CRM will wissen, dass es eine neue Organisation gibt. Events sind die Art, wie die Plattform sagt „das ist passiert“, und Webhooks sind die Art, wie ein anderes System das hört.

Events, Subscriptions und Webhooks

Ein Event ist der Datensatz darüber, dass hier etwas passiert ist: order.placed, product.published, organisation.created. Er trägt, was passiert ist, wann, und die Kennung des Objekts, dem es passiert ist.

Eine Subscription verbindet ein Event mit einer Reaktion: ein Workflow, der läuft, oder ein Webhook, der feuert.

Ein Webhook ist ein HTTP-Aufruf, der die Systemgrenze überschreitet. Ausgehende Webhooks schieben ein Plattform-Event an eine URL, die Ihnen gehört; eingehende Webhooks lassen ein externes System in einen Workflow hier hineinschreiben. In beiden Richtungen ist es ein Push: Der Empfänger wird informiert, statt selbst nachzufragen.

Der Unterschied, der in der Praxis zählt: Ein Event ist eine Tatsache, ein Webhook ist ein Zustellversuch. Zustellungen scheitern, regelmäßig, und alles Weitere auf dieser Seite handelt davon.

Einen Webhook einrichten

1. Öffnen Sie Events › Event-Katalog, um zu sehen, welche Events es gibt und was jedes trägt. Entscheiden Sie anhand des Katalogs, nicht anhand einer Vermutung über den Namen.
2. Gehen Sie zu Webhooks › Ausgehend und legen Sie eine Subscription an.
3. Wählen Sie die Events, die Sie abonnieren. Abonnieren Sie eng. Ein Empfänger, der jedes Event bekommt und die meisten ignoriert, verarbeitet eines Tages eines, das er hätte ignorieren sollen.
4. Tragen Sie die Endpunkt-URL ein. HTTPS, und eine Adresse, die einem System gehört, nicht dem Laptop einer Person.
5. Legen Sie die Authentifizierung fest: ein Shared Secret, ein Signaturschlüssel oder ein Bearer-Token, je nachdem, was der Empfänger erwartet.
6. Legen Sie die Wiederholungsregel fest. Mehrere Versuche mit wachsenden Abständen sind der vernünftige Standard: Ein Empfänger, der gerade neu startet, darf Sie die Nachricht nicht kosten.
7. Senden Sie ein Test-Event und bestätigen Sie, dass der Empfänger mit einem 2xx quittiert.
8. Aktivieren.

Regeln für die Empfängerseite

Den Empfänger kontrollieren Sie oft nicht, aber Sie können auf diesen Punkten bestehen, und zwar schriftlich:

• Schnell quittieren, später verarbeiten. Der Empfänger nimmt die Nutzlast an, antwortet mit 200 und erledigt die Arbeit danach. Ein Empfänger, der vor der Antwort fünf Sekunden ERP-Arbeit macht, läuft unter Last in Timeouts und löst Wiederholungen aus, die die Last vergrößern.
• Auf die Event-ID deduplizieren. Wiederholungen bedeuten, dass dasselbe Event zweimal ankommen kann. Der Empfänger muss eine Wiederholung als Nicht-Operation behandeln. Sonst wird aus einem wiederholten order.placed eine zweite Lieferung.
• Nicht auf die Ankunftsreihenfolge verlassen. Zwei Events, die eine Sekunde auseinander feuern, können in beliebiger Reihenfolge ankommen. Wenn die Reihenfolge zählt, lesen Sie den Zeitstempel in der Nutzlast.
• Die Signatur prüfen. Ein Endpunkt, der jeden POST annimmt, nimmt den POST von jedem an.

Was Sie prüfen

• Das Zustellprotokoll unter Webhooks › Ausgehend. Jeder Versuch mit Antwortcode und Dauer. Anhaltende 4xx heißen, Ihre Nutzlast oder Ihre Zugangsdaten sind falsch; anhaltende 5xx heißen, deren System ist es. Ein langsamer, aber erfolgreicher Endpunkt ist eine Warnung: Er wird an Ihrem stärksten Tag anfangen, in Timeouts zu laufen.
• Die Warteschlange der Fehlschläge. Events, deren Wiederholungen aufgebraucht sind. Sie sollte leer sein. Ist sie es nicht, muss jemand entscheiden, ob die Events erneut gesendet werden, und diese Entscheidung hat eine Frist.
• Volumen in Events › Event-Stream. Eine Event-Zahl, die sich verzehnfacht, bedeutet meist, dass eine Massenoperation Events je Datensatz ausgelöst hat, etwa eine Sammelbearbeitung über 30.000 Produkte. Besser, Sie wissen das, bevor der Empfänger es merkt.

Wann ein Event passt und wann nicht

Die Faustregel: Events sind für Dinge, die passiert sind, eines nach dem anderen, wo Latenz zählt. Massendaten bleiben ein geplanter Workflow.

Weiter

• Syncs überwachen: Zustellungen und Ausführungen gemeinsam im Blick.
• Häufige Sync-Fehler: die Fehlschläge lesen.