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. Der Webhook sendet wie diese Klingel in dem Moment, in dem das festgelegte Ereignis eintritt, eine Anfrage an die festgelegte Stelle.

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. Auch WriteBack, mit dem das vom externen Programm zurückgegebene Ergebnis wieder in das Produkt eingetragen wird, wird dabei behandelt.

Was ein Webhook leistet

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

• Wann gesendet wird: Sie legen fest, bei welchem Ereignis eine Anfrage gesendet wird. Sie können zum Beispiel festlegen: „wenn ein Produkt (Content) neu angelegt wird“.
• Wohin gesendet wird: Sie legen die Adresse des externen Programms fest, das die Anfrage empfängt. Sie tragen eine Internetadresse (URL) ein.
• Ein- oder ausschalten: Sie legen fest, ob dieser Webhook derzeit eingeschaltet (ACTIVE) oder vorübergehend ausgeschaltet (INACTIVE) ist. Im ausgeschalteten Zustand wird keine Anfrage gesendet, selbst wenn das festgelegte Ereignis eintritt.

Wenn das festgelegte Ereignis tatsächlich eintritt, sendet der Webhook eine Anfrage an die eingetragene Adresse, die über diesen Vorgang informiert. In der Anfrage sind 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-Studios 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.

Mit der empfangenen Antwort zurückschreiben: WriteBack

Während der vorige Abschnitt die Form der ausgehenden Anfrage festlegt, behandelt WriteBack die zurückkommende Antwort. Wenn der Webhook das externe Programm aufruft und eine erfolgreiche Antwort (2xx) erhält, kann er diese Antwort aufbereiten und damit innerhalb des Space einen Content oder ein Media erstellen, ändern, veröffentlichen oder löschen. Der Schritt, bei dem ein Mensch das Ergebnis kopiert und einfügt, entfällt.

Verfolgen wir das Übersetzungsbeispiel des Kleidungs-Shops bis zum Ende. Zuvor haben Sie den koreanischen Produktnamen des neuen Produkts an das Übersetzungsprogramm gesendet. Nehmen wir an, das Übersetzungsprogramm antwortet so.

{ "translated": "Stainless Tumbler 500ml" }

Sie richten ein WriteBack ein, das diesen übersetzten Text in das Feld für den englischen Produktnamen desselben Produkts einträgt. Unter WriteBack im Content-Studio fügen Sie über + Operation Hinzufügen eine Update-Aktion (Ändern) für Content hinzu und legen Folgendes fest.

• Ziel: Wenn Sie nichts gesondert festlegen, ist das Produkt, bei dem die Änderung aufgetreten ist (der Tumbler), das Ziel.
• Auszufüllendes Feld und Sprache: Da es der englische Produktname ist, ist das Feld der Produktname (productName) und die Sprache Englisch (en-US).
• Einzutragender Wert: { /response/translated }, der auf den übersetzten Text in der Antwort verweist.

Daraufhin wird das Feld für den englischen Produktnamen des Tumbler-Produkts mit Stainless Tumbler 500ml ausgefüllt.

Ein solches WriteBack ist besonders nützlich, um eine Verbindung zu einem externen LLM herzustellen. Sie können zum Beispiel mit einem einzigen Webhook einen Ablauf einrichten, bei dem ein aus der Produktbeschreibung erzeugtes Werbebild als Media gespeichert wird oder ein neuer Content aus einem generierten Vorstellungstext erstellt wird.

Reihenfolge der Abläufe

1. Tritt eine Änderung ein, sendet der Webhook eine Anfrage in der festgelegten Form an das externe Programm.
2. Ist die Antwort 2xx, werden die hinzugefügten WriteBack-Aktionen (Operationen) von oben nach unten der Reihe nach ausgeführt.
3. Jede Aktion ist von den anderen unabhängig, sodass die übrigen weiter ausgeführt werden, selbst wenn eine fehlschlägt.
4. Auch ein durch WriteBack entstandenes Erstellen, Ändern, Löschen oder Veröffentlichen wird wiederum als Änderung erfasst und kann andere Webhooks, die diese Änderung abonnieren, der Reihe nach auslösen. Ein endlos kreisender Zyklus wird beim Erstellen oder Ändern eines Webhook automatisch geprüft und verhindert.

Der Ersteller (createdBy) einer durch WriteBack erstellten oder geänderten Ressource ist der Nutzer, der diese Änderung ausgelöst hat.

Wertausdrücke

Den einzutragenden Wert holen Sie über denselben Platzhalter ({ /… }), den Sie zuvor gesehen haben. Bei WriteBack gibt es jedoch zwei Wurzeln, auf die verwiesen werden kann.

• Verwenden Sie einen einzelnen Platzhalter allein ({ /response/url }), wird der ursprüngliche Typ des Werts (Text, Zahl, Verbund) unverändert übernommen.
• Mischen Sie ihn mit Text ("Erstellt: { /payload/sys/id }"), wird alles zu einem einzigen Text zusammengefügt.
• Kommt die Antwort nicht als JSON, sondern als reiner Text, empfangen Sie mit { /response } die gesamte Antwort als Text (auf Unterpfade darin kann nicht verwiesen werden).

Content handhaben ($content)

Eine Aktion, die mit der Antwort einen Content erstellt oder ändert. Folgende Punkte werden festgelegt.

Media handhaben ($media)

Eine Aktion, die eine aus der Antwort empfangene Datei als Media einbringt oder den Status eines Media ändert.

$media kann auch als Feldwert eines Content verwendet werden. Sie können eine aus der Antwort empfangene Datei als Media einbringen und dieses Media direkt mit einem Feld verknüpfen und so auf einmal einen „Content mit enthaltenem Bild“ erstellen.

Delete, Archive, Unarchive eines Media behandeln nicht nur die Informationen in der Liste, sondern auch die tatsächliche Datei im Speicher mit.

Einrichtung und Beispiele

Unter WriteBack im Content-Studio fügen Sie über + Operation Hinzufügen Aktionen einzeln hinzu. Sie können zwischen der Methode Visual, bei der Sie die Punkte am Bildschirm ausfüllen, und der Methode JSON, bei der Sie einen writeBacks-Verbund wie unten direkt eintragen, hin- und herwechseln. Das Ergebnis ist in beiden Fällen gleich.

Ein neues Produkt mit einem von einem externen LLM erstellten Bild anlegen. Die in der Antwort enthaltene Bildadresse wird als Media eingebracht und damit ein neuer Content erstellt, der dieses Bild enthält.

{
  "writeBacks": [
    {
      "$content": {
        "action": "Create",
        "contentType": { "sys": { "id": "<sys.id des Produkt-Content-Type>" } },
        "fields": {
          "productName": "{ /payload/fields/productName/ko-KR }",
          "photo": { "$media": { "source": "{ /response/data/0/url }", "encoding": "Url" } }
        }
      }
    }
  ]
}

Das geänderte Produkt selbst anreichern. Lassen Sie target weg, ist der Content, bei dem die Änderung aufgetreten ist, das Ziel. Der Wert aus der Antwort wird in das Feld dieses Produkts eingetragen.

{
  "writeBacks": [
    {
      "$content": {
        "action": "Update",
        "locale": "en-US",
        "fields": { "productName": "{ /response/translated }" }
      }
    }
  ]
}

Nur als Draft erstellen, um nach Prüfung zu veröffentlichen. Schalten Sie publish aus, wird nicht veröffentlicht, sondern als Entwurf belassen, sodass nach Prüfung durch einen Menschen veröffentlicht werden kann.

{
  "writeBacks": [
    {
      "$content": {
        "action": "Create",
        "contentType": { "sys": { "id": "<sys.id des Content-Type>" } },
        "fields": { "text": "{ /response/choices/0/message/content }" },
        "publish": false
      }
    }
  ]
}

Das Antwortbild als eigenständiges Media einbringen. Empfangen Sie es über eine Adresse, setzen Sie encoding auf Url; empfangen Sie es über die in der Antwort enthaltenen Dateidaten, auf Base64.

{
  "writeBacks": [
    { "$media": { "action": "Create", "source": "{ /response/data/0/url }", "encoding": "Url" } }
  ]
}

Delete, Publish, Unpublish, Archive, Unarchive haben dieselbe Form. Tragen Sie nur action und das zu ändernde Ziel target ein, ändert sich nur der Status dieses Ziels (lassen Sie das Ziel weg, ist es das Element, bei dem die Änderung aufgetreten ist). Um zum Beispiel einen Content zu veröffentlichen, den die Antwort mitgeteilt hat, tragen Sie es so ein.

{
  "writeBacks": [
    { "$content": { "action": "Publish", "target": "{ /response/contentId }" } }
  ]
}

Fügen Sie mehrere Aktionen hinzu, werden sie in der eingetragenen Reihenfolge ausgeführt. Etwa indem Sie sie hintereinandersetzen wie „das Übersetzungsergebnis in das Produkt eintragen und anschließend das Werbebild als Media einbringen“.

Ausführungsergebnis prüfen

Wie es jeder WriteBack-Aktion ergangen ist, prüfen Sie im Aufrufprotokoll des Webhook. Zu jeder Aktion bleibt Folgendes erhalten.

Bei einer erfolgreichen Aktion können Sie anhand der Ergebnis-ID nachverfolgen, welche Ressource erstellt oder geändert wurde. Ist die Antwort nicht 2xx, wird WriteBack gar nicht erst ausgeführt, sodass auch das Ergebnisprotokoll leer bleibt.

Was Sie wissen sollten

• Nur eine einzige Änderung sendet die Anfrage. Erfasst ein Webhook gleichzeitig „Anlegen (Create)“ und „Veröffentlichen (Publish)“, kann das externe Programm zweimal aufgerufen werden. Wählen Sie bei einem Webhook, der WriteBack verwendet, nur eine einzige Änderung.
• Es überträgt nur Werte, kann aber nicht rechnen. Es geht nur so weit, Werte aus der Antwort zu entnehmen und einzutragen; eine Verarbeitung wie bedingte Verzweigung oder Schleifen findet nicht statt.
• Es wird nicht erneut versucht. Tritt während der Verarbeitung ein Problem auf, kann diese Aktion ohne Weiteres verloren gehen.
• Nicht beliebig erstellen lassen. Bei einem Content Type, der nur durch WriteBack erstellt wird, empfiehlt es sich, die Berechtigung so einzuschränken, dass normale Nutzer ihn nicht selbst erstellen können.

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 Aufrufprotokoll 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.
• 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.