Webhook

Webhookを利用すると、コンテンツの公開や更新といったCMS上のイベントをトリガーに、外部サービスへHTTPリクエストを送信できます。これにより、CMSの操作を起点としたさまざまな処理を自動化できます。たとえば次のようなユースケースがあります。

コンテンツの公開・非公開をトリガーにWebサイトのデプロイを実行する
コンテンツの公開をSlackチャンネルに通知する
コンテンツの公開・非公開をトリガーにGitHub Actionsのワークフローを実行する

Webhookの送信は、Hook v2とCraft Functionsを組み合わせて実現します。KARTE管理画面のAPI v2アプリにHook v2のトリガーを設定してCMSのイベントを受け取り、Craft Functionsで任意の外部サービスへリクエストを送信します。送信先のURLやリクエストの内容はファンクションのコードとして自由に記述できるため、特定のサービスに依存しない柔軟な連携を実現できます。

このページではWebhookの仕組みと管理画面での設定方法を説明します。実際にファンクションのコードを書いて外部サービスと連携する手順は、チュートリアルのWebhookで外部サービスと連携するを参照してください。

仕組み

CMSのWebhook連携は、次の流れで動作します。

Craft Cross CMSの管理画面でコンテンツを操作する
Hook v2のトリガーによって、Craft Functionsのファンクションが実行される
ファンクション内で外部サービスのURLにHTTPリクエストを送信する

コンテンツ操作 ─→ Hook v2 ─→ Craft Functions ─→ 外部サービス
（CMS管理画面）                （任意の処理）      （Vercel / Slack など）

トリガーになるイベント

Hook v2のトリガーには、次のCMSイベントを指定できます。トリガー設定では「トリガー名」の文字列でイベントを選択します。

トリガー名	イベントタイプ	発生タイミング
KARTE CMS: コンテンツの公開時	`cms/content/publish`	コンテンツを公開したとき
KARTE CMS: コンテンツの非公開時	`cms/content/unpublish`	公開中のコンテンツを非公開にしたとき
KARTE CMS: コンテンツの作成時	`cms/content/create`	コンテンツを新規作成したとき
KARTE CMS: コンテンツの更新時	`cms/content/update`	コンテンツを更新（保存）したとき
KARTE CMS: コンテンツの削除時	`cms/content/delete`	コンテンツを削除したとき
KARTE CMS: コンテンツの並び順変更時	`cms/content/updateOrder`	コンテンツの並び替えを保存したとき

いずれのトリガーも、利用にはAPI v2アプリに beta.cms.content.get スコープが必要です。

Craft Functionsが受け取るデータ

Hook v2経由でCMSイベントが発生すると、ファンクションの引数 data に次の情報が渡されます。

data.kind: "karte/apiv2-hook"
data.jsonPayload.event_type: CMSイベントのタイプ（例: "cms/content/publish"）
data.jsonPayload.data: イベントの内容

data.jsonPayload.data に含まれる情報は、イベントの種類によって異なります。data の全体構造は、Craft Functionsのイベント駆動タイプのファンクションが受け取るデータを参照してください。

コンテンツの公開・非公開・作成・更新イベントのデータ

cms/content/publish、cms/content/unpublish、cms/content/create、cms/content/update のイベントは、操作したコンテンツ1件ごとに送信されます。data.jsonPayload.data には次の情報が含まれます。

id: 操作対象のコンテンツID
sys: コンテンツのシステム情報（Management APIでコンテンツを取得したときの sys と同じ内容）
- modelId: コンテンツが属するモデルID
- customOrder: 表示順を制御するためのカスタム順序の値
- raw.createdAt / raw.updatedAt: コンテンツを作成した日時 / 最後に保存した日時
- raw.firstPublishedAt / raw.publishedAt: コンテンツを初めて公開した日時 / 最後に公開した日時（未公開の場合は null）

{
  "event_type": "cms/content/publish",
  "data": {
    "id": "{コンテンツID}",
    "sys": {
      "modelId": "{モデルID}",
      "customOrder": 1,
      "raw": {
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-01-01T00:00:00.000Z",
        "firstPublishedAt": "2026-01-01T00:00:00.000Z",
        "publishedAt": "2026-01-01T00:00:00.000Z"
      }
    }
  }
}

sys はイベント発生後にコンテンツを取得した時点の値で、上記のほかにも項目が含まれます。すべての項目は、Craft Cross CMSのAPIリファレンスを参照してください。タイトルや本文などのフィールド値は含まれません。フィールド値が必要な場合は、コンテンツIDとモデルIDを使ってManagement APIでコンテンツを取得します。

コンテンツの削除イベントのデータ

cms/content/delete のイベントは、削除したコンテンツ1件ごとに送信されます。削除済みのコンテンツは取得できないため、data.jsonPayload.data には次の情報のみが含まれます。

id: 削除したコンテンツID
sys.modelId: コンテンツが属していたモデルID

{
  "event_type": "cms/content/delete",
  "data": {
    "id": "{コンテンツID}",
    "sys": {
      "modelId": "{モデルID}"
    }
  }
}

並び順変更イベントのデータ

cms/content/updateOrder のイベントは、コンテンツ単位ではなくモデル単位で送信されます。1回の並び替え保存につき、イベントは1件だけ送信されます。data.jsonPayload.data には次の情報が含まれます。

modelId: 並び替えたモデルのID
contentIds: 並び順が変わったコンテンツIDの配列（並び替え後の順序）
publishedContentIds: contentIds のうち、公開側の並び順が変わったコンテンツIDの配列

{
  "event_type": "cms/content/updateOrder",
  "data": {
    "modelId": "{モデルID}",
    "contentIds": ["{コンテンツID}", "{コンテンツID}"],
    "publishedContentIds": ["{コンテンツID}"]
  }
}

下書きのコンテンツだけを並び替えた場合、publishedContentIds は空の配列になります。公開サイトの再デプロイが必要かどうかは、publishedContentIds の件数で判定できます。

並び順変更イベントを利用する際は、次の点に注意してください。

並び替えを保存しても順序が1件も変わらなかった場合、イベントは送信されません
ビュー設定でカスタム順序を有効化したときの採番では、イベントは送信されません
並び替えでは cms/content/update や cms/content/publish のイベントは送信されません。並び替えを検知するには、並び順変更イベントをトリガーに追加してください

管理画面での設定

Webhookを利用するには、管理画面でAPI v2アプリを作成し、Hook v2のトリガーを設定します。

1. API v2アプリを作成する

Hook v2を利用するために、次の設定でAPI v2アプリを作成します。アプリの作成手順やアクセストークンの扱いの詳細は、コンセプトのAPI v2アプリと認証で説明しています。

タイプ: token
スコープ: beta.cms.content.get

作成時に発行されるアクセストークンは、ファンクションから利用するためにCraft Secretへ保存します。アプリの保存時に表示されるモーダルで[Craft Secretへのトークン保存]>[保存]ボタンを押してください（キー名は KARTE_APP_TOKEN など、わかりやすい名前を付けます）。

2. Hook v2のトリガーを設定する

作成したAPI v2アプリにHook v2のトリガーを設定し、CMSのイベント発生時にファンクションが実行されるようにします。

作成したAPI v2アプリの編集画面を開きます
[Hook設定]タブで「編集」を選択します
[トリガー設定]から、利用したいCMSのイベント（トリガーになるイベント）を選択して追加します
[チャンネル設定]>[Craft]>[Hookステータス]>[有効にする]にチェックを付け、Webhook送信処理を実装したファンクションを選択します
アプリ設定を保存します

ここで選択するファンクションの作成方法と、ユースケースごとの実装例は、チュートリアルのWebhookで外部サービスと連携するを参照してください。