Webhook

Ein Webhook ist eine Konfiguration, die eine HTTP-Anfrage an eine vorab festgelegte externe URL sendet, wenn in einem Space etwas geschieht (z. B. die Erstellung oder Veröffentlichung von Content). Er wird für die Anbindung externer Systeme oder für Automatisierung verwendet. So lässt sich beispielsweise konfigurieren, dass bei jeder Veröffentlichung eines Produkt-Content ein interner Benachrichtigungsserver oder eine externe API aufgerufen wird.

Ein Webhook sendet nicht nur eine Anfrage, sondern kann zusätzlich einen WriteBack konfigurieren, der die empfangene Antwort entgegennimmt und zurück in Content oder Media schreibt. Auf diese Weise wird ein asynchroner Arbeitsablauf aufgebaut, der das Ergebnis einer externen API als Daten innerhalb des Space aufnimmt. Ein Webhook ist in der CMA eine untergeordnete Ressource des Space und basiert auf dem Pfad /spaces/{spaceId}/webhooks.

Ressourcenstruktur

Im Folgenden sehen Sie die Antwort der Einzelabfrage des Webhook "Benachrichtigung bei Produktänderung". Neben sys (Systemeigenschaften) enthält er Konfigurationsfelder wie Sendeziel, abonnierte Ereignisse und Auslösebedingungen.

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PWhk01Examp",
    "type": "Webhook",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T11:30:00.000Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T11:30:00.000Z",
    "version": 1
  },
  "name": "Benachrichtigung bei Produktänderung",
  "filters": [
    { "doc": "sys.contentType.sys.id", "op": "EQ", "value": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" }
  ],
  "headers": [
    { "key": "X-Source", "value": "weegloo", "secret": false }
  ],
  "httpBasicUsername": "dailywear",
  "topics": ["Content.Create", "Content.Publish"],
  "transformation": { "method": "POST", "contentType": "application/json", "includeBody": true },
  "url": "https://api.dailywear.example/webhooks/products",
  "activate": true
}

Wichtige Schlüssel:

• sys.id: Eindeutige Kennung des Webhook. Wird im Pfad für Einzelabfrage, Änderung und Löschung als {webhookId} eingesetzt.
• url: Externe Ziel-URL, die beim Eintreten eines Ereignisses aufgerufen wird.
• topics: Array, das festlegt, welche Ereignisse abonniert werden. Das Format wird unten unter topics beschrieben.
• filters: Bedingung, unter der ein abonniertes Ereignis tatsächlich ausgelöst wird. Wird unten unter filters beschrieben.
• transformation: Konfiguration, die die Form der ausgehenden Anfrage (Methode, Body usw.) ändert. Wird unten unter transformation beschrieben.
• writeBacks: Array von Aufgaben, die die externe Antwort entgegennehmen und zurück in Content oder Media schreiben. Im Beispiel oben nicht vorhanden. Wird unten unter writeBacks beschrieben.

Systemeigenschaften (sys)

Jeder Webhook führt gemeinsame Systemeigenschaften im sys-Objekt. space, createdBy und updatedBy werden in der Refer-Form ({ "sys": { "id", "type": "Refer", "targetType" } }) angegeben.

Ein Webhook ist eine Konfigurationsressource und kennt daher kein Konzept der Veröffentlichung. Anders als Content oder Content Type besitzt er keine Veröffentlichungsstatus-Eigenschaften wie publish, archive oder status, sondern nur die version zur Änderungsverfolgung. Das Ein- und Ausschalten erfolgt nicht über Veröffentlichung, sondern wird über das Body-Feld activate gesteuert.

Body-Eigenschaften

Der Body eines Webhook (die Konfigurationswerte, die bei Erstellung und Änderung gesendet werden und in der Antwort zurückkommen) besteht aus den folgenden Feldern.

Jeder Eintrag in headers besteht aus key (erforderlich), value (erforderlich) und secret (optional, boolean). Bei einem Header mit secret gleich true wird der Wert in der Antwort verdeckt. Werte, die nicht offengelegt werden dürfen, wie etwa API-Schlüssel, gehören in einen Header mit secret: true.

topics

Jeder Eintrag in topics hat das Format {Ressource}.{Aktion}. Beispiel: Content.Create, Content.Publish, Media.Create.

Die Aktion ist entweder eine der folgenden oder das *, das alle Aktionen der Ressource bedeutet (z. B. Content.*).

filters

filters ist ein Array, das eingrenzt, welche der abonnierten topics den Webhook tatsächlich auslösen. Jeder Filter hat die folgende Form.

{ "doc": "sys.contentType.sys.id", "op": "EQ", "value": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" }

• doc: Zu vergleichender Feldpfad. Einer von sys.id, sys.contentType.sys.id, sys.createdBy.sys.id, sys.updatedBy.sys.id.
• op: Vergleichsoperator. Einer von EQ, NE, IN, NOT_IN, REGEX, NOT_REGEX.
• value: Vergleichswert. Bei EQ, NE, REGEX, NOT_REGEX ein String, bei IN, NOT_IN ein String-Array.

Sind mehrere Filter gesetzt, muss die Auslösung alle erfüllen (AND). Ist filters leer, lösen alle Ereignisse der abonnierten topics aus.

transformation

transformation ändert die Form der ausgehenden HTTP-Anfrage. Ohne Angabe geht die gesamte Ressourcen-Payload unverändert per Standard-POST hinaus.

writeBacks

writeBacks ist ein geordnetes Array von Aufgaben, die die von einem Webhook empfangene externe Antwort verwenden, um zurück in Content oder Media zu schreiben. Sie werden nur dann der Reihe nach ausgeführt, wenn die externe API mit 2xx antwortet. Jeder Eintrag enthält entweder ein $content (WriteBackContent) oder ein $media (WriteBackMedia).

Schlüssel von WriteBackContent ($content):

Schlüssel von WriteBackMedia ($media):

Im Folgenden sehen Sie ein writeBacks-Beispiel, das Werte aus dem externen Antwort-JSON entnimmt und damit einen Content erstellt.

"writeBacks": [
  {
    "$content": {
      "action": "Create",
      "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" } },
      "locale": "ko-KR",
      "fields": {
        "productName": "{ /response/title }",
        "price": "{ /response/price }"
      },
      "publish": true,
      "unpublish": true
    }
  }
]

{ /response/... } ist eine JSON-Pointer-Vorlage, die einen Wert aus dem vom Webhook empfangenen Antwort-JSON entnimmt. Die Schlüssel von fields (productName, price) sind der apiName der Ziel-Content-Felder. Das Beispiel oben füllt das title der Antwort in das productName des Content und das price in price, erstellt damit den Content und veröffentlicht ihn anschließend.

API

Die Basis-URL aller Endpunkte unten ist https://cma.weegloo.com/v1, und im Authorization-Header ist ein Bearer-Token zur Authentifizierung an der CMA erforderlich. Bei Änderung (PUT) und Teiländerung (PATCH) muss zur optimistischen Nebenläufigkeitskontrolle der Header X-Weegloo-Version (die sys.version der aktuellen Ressource) mitgesendet werden.

Verwandte Dokumente

• Content: Body-Daten, die einen Webhook auslösen oder per WriteBack geschrieben werden.
• Media: Dateiressource, die per WriteBack erstellt werden kann.
• SpaceRole: Wenn der Zugriff auf den Arbeits-Content eines Webhook mit :self beschränkt wird.