コンテンツにスキップ
KARTE Craft Developer Portal

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連携は、次の流れで動作します。

  1. Craft Cross CMSの管理画面でコンテンツを操作する
  2. Hook v2のトリガーによって、Craft Functionsのファンクションが実行される
  3. ファンクション内で外部サービスの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コンテンツを削除したとき

いずれのトリガーも、利用には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.id: 操作対象のコンテンツID
  • data.jsonPayload.data.sys: コンテンツのシステム情報
  • data.jsonPayload.data.sys.modelId: コンテンツが属するモデルID

data の全体構造は、Craft Functionsのイベント駆動タイプのファンクションが受け取るデータを参照してください。

ペイロードに含まれるのはコンテンツID（id）とシステム情報（sys）で、タイトルや本文などのフィールド値は含まれません。フィールド値が必要な場合は、コンテンツIDとモデルIDを使ってManagement APIでコンテンツを取得します。なお、コンテンツの削除イベント（cms/content/delete）では、sys に modelId のみが含まれます。

管理画面での設定

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で外部サービスと連携するを参照してください。