Webhook

Webhook は、Space で何かが起きたとき (例: Content の作成・公開) に、あらかじめ指定した外部 URL へ HTTP リクエストを送る設定です。外部システム連携や自動化に使います。たとえば商品 Content が公開されるたびに社内通知サーバーを呼び出したり、外部 API を呼び出すように構成できます。

Webhook はリクエストを送るだけでなく、その応答を受け取って再び Content や Media へ書き戻す WriteBack まで設定できます。外部 API の結果を Space 内のデータとして取り込む非同期ジョブのフローを、このように構成します。Webhook は CMA における Space 配下のリソースで、パスは /spaces/{spaceId}/webhooks を基準とします。

リソース構造

次は Webhook「商品変更通知」の単一取得レスポンスです。sys (システムプロパティ) とあわせて、送信先・購読イベント・トリガー条件といった設定フィールドを持ちます。

{
  "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": "商品変更通知",
  "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
}

主なキー:

• sys.id: Webhook の一意な識別子です。単一取得・修正・削除パスの {webhookId} に入ります。
• url: イベントが発生したときに呼び出す外部の対象 URL です。
• topics: どのイベントを購読するかを定めた配列です。下記の topics で形式を説明します。
• filters: 購読したイベントのうち、実際にトリガーする条件です。下記の filters で説明します。
• transformation: 送り出すリクエストの形 (メソッド・本文など) を変える設定です。下記の transformation で説明します。
• writeBacks: 外部応答を受け取って Content や Media へ書き戻すジョブの配列です。上記の例にはありません。下記の writeBacks で説明します。

システムプロパティ (sys)

すべての Webhook は共通のシステムプロパティを sys オブジェクトに格納します。space・createdBy・updatedBy は Refer の形 ({ "sys": { "id", "type": "Refer", "targetType" } }) で入ります。

Webhook は設定リソースなので、公開という概念がありません。Content や Content Type とは違い、publish・archive・status のような公開状態のプロパティを持たず、変更追跡用の version だけを持ちます。オン・オフは公開ではなく、本文フィールド activate で制御します。

本文プロパティ

Webhook の本文 (作成・修正時に送り、応答として返ってくる設定値) は次のフィールドで構成されます。

headers の各項目は key (必須)・value (必須)・secret (任意, boolean) で構成されます。secret が true のヘッダーは応答で値が隠されます。 API キーのように露出してはいけない値は secret: true のヘッダーに置きます。

topics

topics の各項目は {リソース}.{アクション} の形式です。例: Content.Create, Content.Publish, Media.Create。

アクションは次のいずれか、またはリソースのすべてのアクションを意味する * です (例: Content.*)。

filters

filters は、購読した topics のうち実際に Webhook をトリガーする条件を絞り込む配列です。各フィルターは次の形です。

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

• doc: 比較するフィールドのパス。sys.id・sys.contentType.sys.id・sys.createdBy.sys.id・sys.updatedBy.sys.id のいずれかです。
• op: 比較演算子。EQ・NE・IN・NOT_IN・REGEX・NOT_REGEX のいずれかです。
• value: 比較値。EQ・NE・REGEX・NOT_REGEX には文字列を、IN・NOT_IN には文字列の配列を渡します。

複数のフィルターを置くと、すべてを満たした場合にトリガーします (AND)。filters を空にすると、購読した topics のすべてのイベントがトリガーします。

transformation

transformation は、送り出す HTTP リクエストの形を変えます。指定しない場合は、リソースのペイロード全体がデフォルトの POST でそのまま送られます。

writeBacks

writeBacks は、Webhook が受け取った外部応答を使って Content や Media へ書き戻すジョブの、順序付き配列です。外部 API が 2xx で応答したときだけ、順番に実行されます。各項目は $content (WriteBackContent) または $media (WriteBackMedia) を 1 つ持ちます。

WriteBackContent ($content) のキー:

WriteBackMedia ($media) のキー:

次は、外部応答 JSON から値を取り出して Content を 1 つ作る writeBacks の例です。

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

{ /response/... } は、Webhook が受け取った応答 JSON から値を取り出す JSON Pointer テンプレートです。fields のキー (productName・price) は、対象 Content フィールドの apiName です。上記の例は、応答の title を Content の productName に、price を price に埋めて Content を作り、その後に公開します。

API

以下のすべてのエンドポイントの基準 URL は https://cma.weegloo.com/v1 で、Authorization ヘッダーに CMA を認証する Bearer トークンが必要です。修正 (PUT) と部分修正 (PATCH) は、楽観的同時実行制御のために X-Weegloo-Version ヘッダー (現在のリソースの sys.version) もあわせて送る必要があります。

関連ドキュメント

• Content: Webhook がトリガーされる、または WriteBack で書き込む本文データ。
• Media: WriteBack で作成できるファイルリソース。
• SpaceRole: Webhook ジョブの Content へのアクセスを :self で制限するとき。