Webhook

Stellen Sie sich vor, Sie betreiben einen Online-Shop für Kleidung. Jedes Mal, wenn Sie ein neues Produkt anlegen, fallen Folgeaufgaben an, um die Sie sich jedes Mal selbst kümmern müssen. Etwa die Produktbeschreibung in eine andere Sprache zu übersetzen oder im internen Firmen-Messenger zu melden, dass ein Produkt angelegt wurde. Solche Folgeaufgaben müssen Sie nicht jedes Mal von Hand erledigen: In dem Moment, in dem ein Produkt angelegt wird, kann ein externes Programm automatisch benachrichtigt werden und die Aufgabe stellvertretend übernehmen. Diese „Vorrichtung, die bei einem bestimmten Ereignis automatisch eine vorab festgelegte Stelle benachrichtigt“ ist der Webhook.

Man kann es mit einer Türklingel am Eingang des Ladens vergleichen. Wenn ein Kunde die Tür öffnet und hereinkommt (wenn ein Produkt angelegt wird), klingelt die Klingel von selbst, und ein Mitarbeiter im Inneren (das externe Programm) bemerkt sofort „Es ist ein Kunde da“ und wird tätig. Niemand muss ständig die Tür im Blick behalten. Wie diese Klingel startet der Webhook in dem Moment, in dem ein festgelegtes Ereignis eintritt, automatisch eine festgelegte Aktion.

Auf dieser Seite sehen wir uns zuerst an, was ein Webhook ist und in welchen Fällen er verwendet wird. Anschließend legen Sie im Space des Kleidungs-Shops selbst einen Webhook an.

Was ein Webhook leistet

Ein Webhook besteht aus drei Dingen, die Sie vorab festlegen.

• Wann: Sie legen fest, bei welchem Ereignis er reagieren soll. Sie können zum Beispiel festlegen: „wenn ein Produkt (Content) neu angelegt wird“.
• Was getan wird: Sie legen eines von zwei Dingen fest. Entweder wird eine Anfrage an die Internetadresse (URL) eines externen Programms gesendet, oder es wird ein Script ausgeführt, das Sie in Ihrem Space erstellt haben.
• Ein- oder ausschalten: Sie legen fest, ob dieser Webhook derzeit eingeschaltet (Active) oder vorübergehend ausgeschaltet (Inactive) ist. Im ausgeschalteten Zustand geschieht nichts, selbst wenn das festgelegte Ereignis eintritt.

Wenn das festgelegte Ereignis tatsächlich eintritt, führt der Webhook die festgelegte Aktion aus. Wird an eine externe Adresse gesendet, sind in der Anfrage Informationen enthalten wie etwa, was geschehen ist und bei welchem Produkt es geschehen ist. Das externe Programm, das die Anfrage empfängt, sieht sich diese Informationen an und erledigt seine eigene Aufgabe.

Bei welcher Änderung eine Anfrage gesendet wird

Das „Ereignis“, das eine Anfrage auslöst, ist eine Änderung an einer Ressource innerhalb des Space. Sie können auswählen, wann etwas geschieht bei einem Content wie einem Produkt, bei Media als hochgeladener Datei oder bei einem Content Type als Formularvorlage.

Je nach Ressource sind folgende Änderungen wählbar.

„Sende jedes Mal eine Anfrage, wenn ein Produkt neu angelegt wird“ bedeutet zum Beispiel, dass Sie „Create von Produkt (Content)“ auswählen.

Sie können in einem einzigen Webhook auch mehrere Änderungen zusammen auswählen. Wählen Sie sowohl „wenn ein Produkt angelegt wird“ als auch „wenn ein Produkt geändert wird“, geht bei jedem der beiden Vorgänge eine Anfrage hinaus.

Mit Bedingungen eingrenzen

Manchmal möchten Sie nicht bei jedem Eintreten der gewählten Änderung eine Anfrage senden. Sie möchten zum Beispiel nur empfangen, „wenn nicht jeder beliebige Content, sondern ein mit der Vorlage ‚Produkt‘ erstellter Content angelegt wird“. In diesem Fall grenzen Sie mit einem Filter die Fälle ein, in denen eine Anfrage gesendet wird.

Ein einzelner Filter besteht aus einer Zeile: „wonach und wie verglichen wird“. Wonach gefiltert wird, wählen Sie aus vier Möglichkeiten.

• Mit welcher Vorlage das Element erstellt wurde: Es wird zum Beispiel nur an Content gesendet, der mit dem Content Type „Produkt“ erstellt wurde. Das ist die am häufigsten verwendete Bedingung.
• Ob es ein bestimmtes einzelnes Element ist: Es wird nur an Änderungen gesendet, die an genau diesem einen festgelegten Element auftreten.
• Wer das Element erstellt hat: Es wird nur an Elemente gesendet, die eine bestimmte Person erstellt hat.
• Wer das Element zuletzt geändert hat: Es wird nur an Elemente gesendet, die eine bestimmte Person zuletzt geändert hat.

Sie wählen auch die Vergleichsweise mit. Sie können eingrenzen auf: nur wenn der Wert dem festgelegten Wert entspricht, nur wenn er abweicht, nur wenn er einem von mehreren festgelegten Werten entspricht, nur wenn er keinem davon entspricht, oder nur wenn er einem festgelegten Format (Muster) entspricht beziehungsweise nicht entspricht.

In den Trigger-Einstellungen des Content Studio fügen Sie über Filter Hinzufügen Zeile für Zeile eine Bedingung hinzu. Legen Sie mehrere Filter an, geht eine Anfrage nur dann hinaus, wenn alle dieser Bedingungen erfüllt sind. Legen Sie keinen einzigen an, geht bei jedem Eintreten der gewählten Änderung eine Anfrage hinaus.

In der vom externen Programm gewünschten Form senden

Wenn Sie nichts gesondert festlegen, wird in der Anfrage die gesamte Information des geänderten Elements mitgesendet. Wird zum Beispiel das Produkt „Edelstahl-Tumbler 500 ml“ angelegt, sieht der Inhalt, der in der Anfrage mitgeht, ungefähr so aus.

{
  "sys": { "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq", "type": "Content" },
  "fields": {
    "productName": { "ko-KR": "스테인리스 텀블러 500ml" }
  }
}

(Tatsächlich sind mehr Informationen enthalten; oben ist nur ein Ausschnitt davon dargestellt.) Das externe Programm wählt daraus die benötigten Werte aus und verwendet sie. Es gibt jedoch auch Programme, deren Format festgelegt ist und die „nur in dieser Form empfangen wollen“. In diesem Fall wählen Sie im Content Studio unter Payload die Option Webhook-Payload anpassen und tragen die zu sendende Form selbst ein.

Tragen Sie die zu sendende Form ein, verwenden Sie aber an den Stellen, an denen ein Wert aus den obigen Daten eingesetzt werden soll, einen Platzhalter. Ein Platzhalter hat die Form { /payload/… }. Hier verweist payload auf das gesamte oben gezeigte Element, und der nachfolgende Pfad greift genau den gewünschten Wert heraus.

• { /payload/sys/id } → id innerhalb von sys in den obigen Daten (die eindeutige Nummer des Produkts)
• { /payload/fields/productName/ko-KR } → ko-KR von productName innerhalb von fields (der koreanische Produktname). Nach fields/ setzen Sie nacheinander die ID des Field (für den Produktnamen productName) und den Sprachcode (für Koreanisch ko-KR).

Verlangt ein Übersetzungsprogramm zum Beispiel „gib mir den zu übersetzenden Text und die Produktnummer in dieser Form“, tragen Sie das Payload so ein.

{
  "id": "{ /payload/sys/id }",
  "text": "{ /payload/fields/productName/ko-KR }"
}

In dem Moment, in dem das Tumbler-Produkt angelegt wird, werden die Platzhalter durch die tatsächlichen Werte ersetzt und so übermittelt.

{
  "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq",
  "text": "스테인리스 텀블러 500ml"
}

Denselben Platzhalter können Sie auch in der Sende-Adresse (URL) oder in Header-Werten einsetzen, und auch die Sendeweise (method) sowie das Format (JSON oder Formularformat) lassen sich mit auswählen. Hat der angegebene Pfad keinen Wert, bleibt diese Stelle leer.

Werte, die anderen nicht sichtbar sein dürfen, etwa ein externer API-Schlüssel, setzen Sie beim Hinzufügen eines Headers dessen Typ auf Secret. Der Wert wird dann verdeckt gespeichert und gegenüber Endnutzern nicht offengelegt.

Statt einer URL ein Script ausführen

Bisher hat der Webhook eine Anfrage an eine externe Adresse (URL) gesendet. Stattdessen kann ein Webhook auch ein Script ausführen, das Sie in Ihrem Space erstellt haben. Ein Script ist eine Vorrichtung, die eine von Ihnen festgelegte Arbeit (Ressourcen erstellen und ändern und so weiter) innerhalb Ihres Space erledigt, ohne nach außen zu gehen. Diese Vorgehensweise verwenden Sie, wenn Sie die Folgeaufgaben innerhalb Ihres Space abschließen möchten, ohne den Umweg über ein externes Programm zu nehmen.

Ein einzelner Webhook tut genau eines von beiden: an eine externe Adresse senden oder ein Script ausführen. Sie legen dies auf dem Anlege-Bildschirm unter Ziel der Anfrage fest. Wählen Sie URL direkt eingeben, wird wie zuvor eine Anfrage an die Adresse gesendet; wählen Sie hingegen ein Script aus der Liste, wird dieses Script ausgeführt.

Wählen Sie ein Script aus, erscheint zusätzlich Run as, womit Sie festlegen, unter wessen Identität dieses Script ausgeführt wird. Sie wählen eines von beiden.

• Ersteller des Webhook (Standard): Als „Ersteller“ jeder während der Ausführung erstellten oder geänderten Ressource bleibt die Person eingetragen, die den Webhook erstellt hat.
• Auslösender Benutzer: Es bleibt der Nutzer eingetragen, der diese Änderung ausgelöst hat.

Diese Einstellung legt nur die Markierung „wer es getan hat“ fest, die an den Ressourcen zurückbleibt; sie erweitert oder verengt nicht, was das Script tun kann. Der Umfang dessen, was ein Script tun darf, ist bereits festgelegt, wenn Sie es erstellen.

Konkret wählen Sie in dieser Reihenfolge aus:

1. Klicken Sie auf dem Anlege-Bildschirm auf Ziel der Anfrage.
2. Wählen Sie aus der Liste das auszuführende Script aus. Sie wählen also ein Script statt URL direkt eingeben.
3. Wählen Sie unter Run as die Identität aus. Der Standard ist Ersteller des Webhook.

Was ein Script ist und wie Sie eines erstellen, wird unter Script behandelt.

Einen Webhook für den Kleidungs-Shop anlegen

Jetzt legen wir im Space des Kleidungs-Shops einen Webhook an. Es ist ein Webhook, der besagt: „Wenn ein neues Produkt angelegt wird, benachrichtige das vorab vorbereitete externe Übersetzungsprogramm darüber.“ Als Adresse des externen Programms, das die Anfrage empfängt, nehmen wir https://example.com/translate.

1. Öffnen Sie in den Einstellungen des Space des Kleidungs-Shops den Webhook-Bildschirm.
2. Klicken Sie oben rechts auf die Schaltfläche Erstellen.
3. Geben Sie in das Namensfeld Benachrichtigung über neue Produktübersetzung ein. Dieser Name dient später dazu, zu erkennen, um welchen Webhook es sich handelt.
4. Legen Sie die Änderung fest, bei der eine Anfrage gesendet wird. Um nur bei einer bestimmten Änderung zu senden, wählen Sie Bestimmte auslösende Ereignisse auswählen und geben dann die gewünschte Änderung an (hier Create von Produkt (Content)); um bei allen Änderungen zu senden, wählen Sie Für alle Ereignisse auslösen.
5. Geben Sie in das Feld URL die Adresse des externen Programms ein, das die Anfrage empfängt: https://example.com/translate.
6. Lassen Sie Aktiv eingeschaltet, wird sofort nach dem Anlegen eine Anfrage gesendet (Active). Wollen Sie zunächst nur testen, lassen Sie es ausgeschaltet (Inactive).
7. Klicken Sie auf die Schaltfläche Erstellen, um den Webhook anzulegen.

Erscheint in der Liste Benachrichtigung über neue Produktübersetzung im Status Active, ist der Webhook angelegt.

Legen Sie danach im Kleidungs-Shop tatsächlich ein neues Produkt an. In dem Moment, in dem Sie es anlegen, sendet der Webhook eine Anfrage an die eingetragene Adresse. Ob die Anfrage erfolgreich hinausging und wie das externe Programm geantwortet hat, können Sie im Aufrufverlauf des Webhook prüfen.

Ein- und Ausschalten sowie Ändern

Einen Webhook können Sie auch nach dem Anlegen jederzeit ein- und ausschalten. Wollen Sie die Anfragen vorübergehend anhalten, löschen Sie ihn nicht, sondern schalten Sie ihn auf Inactive aus. Während er ausgeschaltet ist, geht keine Anfrage hinaus, auch wenn Sie ein neues Produkt anlegen. Schalten Sie ihn wieder auf Active ein, werden ab da wieder Anfragen gesendet.

Öffnen Sie den angelegten Webhook erneut, können Sie Aktiv aus- oder wieder einschalten. Auch Inhalte wie den Namen, die Adresse, an die die Anfrage gesendet wird, und die auslösende Änderung können Sie später ändern, und einen Webhook, den Sie nicht mehr verwenden, können Sie löschen.

Nächste Schritte

• Content-Modellierung: behandelt, wie Sie die Formularvorlage für einen Content wie „Produkt“ erstellen, der das Ziel der vom Webhook ausgelösten Anfrage ist.
• Content erstellen: hier können Sie ein echtes Produkt anlegen und prüfen, ob der Webhook funktioniert.
• Script: behandelt, wie Sie die innerhalb Ihres Space laufende Arbeit erstellen, die ein Webhook statt einer URL ausführen kann.
• API-Referenz: behandelt die Anfrage- und Antwortformate sowie die Feldspezifikation, die Sie verwenden, wenn Sie einen Webhook direkt aus einem Programm heraus erstellen und verwalten.