Webhooks

Ein Trigger im Webhook-Modus löst im Moment des Quellereignisses aus, statt auf die nächste Abfrage zu warten. Derzeit funktionieren Stripes Zahlungsereignis-Trigger und der eingehende Trigger jeder eigenen App auf diese Weise — siehe Integrationen für die vollständige, aktuelle Liste, welche Trigger Abfrage- bzw. Webhook-basiert sind.

Ihre Webhook-URL finden

Sobald ein Roboter mit einem Trigger-Schritt im Webhook-Modus bei der Arbeit ist, zeigt die Karte dieses Schritts eine echte, eindeutige URL — kopieren Sie sie von dort. Sie erscheint erst, nachdem der Roboter an die Arbeit geschickt wurde, da die URL (und ihr Sicherheitstoken) zu diesem Zeitpunkt generiert wird, nicht bei der ersten Erstellung des Schritts.

Sicherheitsmodell

Jede Webhook-URL bettet ein langes, nicht erratbares Zufalls-Token direkt in den Pfad ein — dieses Token ist die Zugangsberechtigung. Es gibt nichts zu konfigurieren, außer die URL dort einzufügen, wo der Anbieter (oder Ihr eigenes System) nach einem Webhook-Endpunkt fragt. Stripe unterstützt zusätzlich ein Signing-Secret, das beim Verbinden von Stripe eingegeben wird und das Gate97 nutzt, um zu prüfen, dass jedes Ereignis wirklich von Stripe stammt, bevor darauf reagiert wird — richten Sie dies ein, wenn Sie diese zusätzliche Prüfung möchten; ohne sie werden Ereignisse weiterhin akzeptiert, nur unverifiziert.

Wie die Zustellung funktioniert

Gate97 bestätigt eine Webhook-Anfrage sofort und verarbeitet sie im Hintergrund, sodass der Anbieter nie auf eine Zeitüberschreitung wartet. Sowohl POST als auch PUT werden akzeptiert. Doppelte Zustellungen (Anbieter wiederholen häufig, wenn sie keine ausreichend schnelle Antwort erhalten) werden erkannt und erzeugen nur einen Durchlauf.

Eingehende Webhooks eigener Apps

Eine eigene App mit aktiviertem Unterstützt eingehenden Trigger funktioniert genauso — ihr Trigger-Schritt erhält eine echte Webhook-URL, sobald der Roboter bei der Arbeit ist, und alles, was Sie dorthin senden, wird gemäß dem konfigurierten Format (JSON, XML, CSV oder Klartext) geparst und wird als {{trigger.*}} für den Rest des Roboters verfügbar. Dies ist der Mechanismus, damit Ihre eigenen Systeme Daten in Gate97 pushen können, statt dass Gate97 sie abfragt. Siehe Eigene Apps, wie man eine einrichtet.

Aufruf mit curl

Die URL, die Sie von einem Trigger-Schritt eines arbeitenden Roboters kopieren, hat bereits genau die untenstehende Form — nichts selbst auszufüllen. Ein paar durchgerechnete Beispiele, eines pro unterstütztem Format:

JSON (Standard — ein für json konfigurierter Trigger):

curl -X POST "https://gate97.com/api/webhooks/custom:3f2a1b4c-9d21-4e3f-8a6b-1c2d3e4f5a6b/8f3e9c2a1b4d5e6f7a8b9c0d1e2f3a4b" \
  -H "Content-Type: application/json" \
  -d '{"orderId": "1234", "status": "paid"}'

PUT funktioniert identisch — beide Methoden werden auf derselben URL akzeptiert:

curl -X PUT "https://gate97.com/api/webhooks/custom:3f2a1b4c-9d21-4e3f-8a6b-1c2d3e4f5a6b/8f3e9c2a1b4d5e6f7a8b9c0d1e2f3a4b" \
  -H "Content-Type: application/json" \
  -d '{"orderId": "1234", "status": "shipped"}'

XML (ein für xml konfigurierter Trigger):

curl -X POST "https://gate97.com/api/webhooks/custom:3f2a1b4c-9d21-4e3f-8a6b-1c2d3e4f5a6b/8f3e9c2a1b4d5e6f7a8b9c0d1e2f3a4b" \
  -H "Content-Type: application/xml" \
  -d '<order><id>1234</id><status>paid</status></order>'

CSV (ein für csv konfigurierter Trigger) — jede Zeile wird zu ihrem eigenen Durchlauf, wobei die Spalten dieser Zeile als {{trigger.*}} verfügbar sind:

curl -X POST "https://gate97.com/api/webhooks/custom:3f2a1b4c-9d21-4e3f-8a6b-1c2d3e4f5a6b/8f3e9c2a1b4d5e6f7a8b9c0d1e2f3a4b" \
  -H "Content-Type: text/csv" \
  --data-binary $'name,email\nJane Doe,jane@example.com\nJohn Smith,john@example.com'

Der obige Content-Type-Header dient der Lesbarkeit — Gate97 parst den Body immer im Format, das Sie bei der Definition der eigenen App gewählt haben, unabhängig vom Header, den der Absender setzt. Ein erfolgreicher Aufruf erhält sofort eine schnelle, leere 200-Antwort; der Durchlauf selbst findet im Hintergrund statt; prüfen Sie die Ausführungshistorie dieses Roboters, um das Ergebnis zu sehen. Ein leerer Anfrage-Body wird verworfen, ohne einen Durchlauf zu erzeugen, statt einen Fehler auszulösen.