microCMS

コンテンツのWebhookを設定

最終更新日:2023年11月24日

コンテンツの変更時に他システムとの連携を行うため、microCMSではWebhook機能を用意しています。
設定は各APIの「API設定」→「Webhook」で行います。



この画面で「追加」ボタンを押して追加したいWebhookを選び、設定を行ってください。
現在設定できるWebhookは以下の9種類です。

  • Slack
  • Chatwork
  • Netlify
  • Cloudflare Pages
  • Vercel
  • AWS Amplify
  • GitHub Actions
  • メール通知
  • カスタム通知

Webhookのタイミング

各Webhookの設定時にWebhookを発行するタイミングを設定できます。


1. コンテンツの公開時・更新時

コンテンツが「公開中」になった際や、「公開中」もしくは「公開中かつ下書き中」のコンテンツに変更があった際に通知を行います。

コンテンツ編集画面による操作

microCMSのコンテンツ編集画面での操作によって新規公開や公開済みコンテンツが更新された際に通知を行います。

APIによる操作

WRITE API(PUT / PATCH / DELETE)によって新規公開や公開済みコンテンツが更新された際に通知を行います。

レビューによる公開

レビュー申請機能によって新規公開や公開済みコンテンツが更新された際に通知を行います。

予約設定による操作

コンテンツの予約公開機能によって新規公開や公開済みコンテンツが更新された際に通知を行います。

コンテンツの並び替え

公開済みのコンテンツをmicroCMSのコンテンツ一覧画面で並び替えた際に通知を行います。

コンテンツIDの変更

公開済みのコンテンツのコンテンツIDを更新した際に通知を行います。

公開日時の変更

公開済みのコンテンツの公開日時を更新した際に通知を行います。

カスタムステータスの変更

公開済みのコンテンツのカスタムステータスを更新した際に通知を行います。

2. コンテンツの非公開時

コンテンツが「公開中」から「公開終了」もしくは「下書き中」に変更された際に通知します。

コンテンツ編集画面による操作

microCMSのコンテンツ編集画面での操作によって、公開中のコンテンツが公開終了もしくは下書き中に変更された際に通知します。

予約設定による操作

コンテンツの予約非公開機能によって公開中のコンテンツが公開終了に変更された際に通知します。

3. コンテンツの下書き保存時

コンテンツが「下書き中」もしくは「公開中かつ下書き中」になった際や、「下書き中」のコンテンツに変更があった際に通知します。

コンテンツ編集画面による操作

microCMSのコンテンツ編集画面での操作によって下書き中コンテンツが更新された際に通知を行います。

APIによる操作

下書き中のコンテンツに対するPATCH APIでのコンテンツ編集の際に通知を行います。

コンテンツの並び替え

下書き中のコンテンツをmicroCMSのコンテンツ一覧画面で並び替えた際に通知を行います。

コンテンツIDの変更

下書き中のコンテンツのコンテンツIDを更新した際に通知を行います。

公開日時の変更

下書き中のコンテンツの公開日時を更新した際に通知を行います。

カスタムステータスの変更

下書き中のコンテンツのカスタムステータスを更新した際に通知を行います。

4. 公開中コンテンツの削除時

公開中のコンテンツが削除された際に通知します。

コンテンツ編集画面による操作

microCMSのコンテンツ編集画面での操作によってコンテンツが削除された際に通知を行います。

APIによる操作

DELETE APIによってコンテンツが削除された際に通知を行います。

5. 下書きコンテンツの削除時

下書き中のコンテンツが削除された際に通知します。

コンテンツ編集画面による操作

microCMSのコンテンツ編集画面での操作によってコンテンツが削除された際に通知を行います。

APIによる操作

DELETE APIによってコンテンツが削除された際に通知を行います。

6. 公開中かつ下書き中コンテンツの下書き破棄時

公開中かつ下書き中コンテンツの下書きを破棄した際に通知を行います。

7. APIの設定変更時

APIの基本設定やスキーマなど、何らかの変更を行った際に通知します。

8. APIの削除時

APIが削除された際に通知します。

設定内容と動作内容

Slack

SlackへのWebhookには以下の情報が必須で必要です。
Slack側の操作については公式ドキュメント等をご参照ください。

  • Slackで発行するWebhook URL


実際に通知が行われる際は以下のような形で行われます。
URL部分にはデフォルトでは管理画面のURLが入りますが、設定で任意のURLに変更することも可能です。

Chatwork

ChatworkへのWebhookには以下の情報が必須で必要です。

  • ChatworkのAPIトークン:Chatworkドキュメント
  • 部屋ID:通常URLに含まれる rid000000000 のうちの数値部分です。


通知内容はSlackと同様となります。

Netlify

microCMSからのWebhookによってビルド処理を開始できます。
設定内容は下記の通りです。

Cloudflare Pages

microCMSからのWebhookによってビルド処理を開始できます。
設定内容は下記の通りです。

Vercel

microCMSからのWebhookによってビルド処理を開始できます。
設定内容は下記の通りです。

AWS Amplify

microCMSからのWebhookによってビルド処理を開始できます。
設定内容は下記の通りです。

GitHub Actions

microCMSからのWebhookによってビルド処理を開始できます。
設定内容は下記の通りです。

tipsTips

GitHub Actionsの設定方法の詳細については、ヘルプ記事「【コンテンツのWebhook連携】GitHub Actionsの設定方法について」をご覧ください。

informationInformation

トークンが有効期限になった際は、新規にトークンを取得いただき、値を上書きして設定できます。

メール通知

コンテンツやAPIの変更時などに指定したメールアドレスに変更内容を送信できます。
設定内容は下記の通りです。

  • メールアドレス


また、SlackやChatworkのWebhookと同様に、本文内にはURLが含まれますがこちらも任意のものに変更可能です。

カスタム通知

任意のURLに対してPOSTリクエストを送信します。
設定内容は下記の通りです。

  • POST先となるURL

カスタム通知について

カスタム通知では任意のURLに対してPOSTリクエストを送信します。
あらゆるURLを指定可能ですので、リクエストを受け取った側は独自の処理を自由に行ってください。

シークレット(Webhookのセキュリティ保護)

microCMSにはWebhookリクエストがmicroCMSからのものであることを検証するためのヘッダ値を付与できます。
付与にあたってはシークレット値を設定する必要があり、microCMSでは設定することを推奨いたします。

シークレット値が設定されている場合のみ、リクエストのヘッダにX-MICROCMS-Signature: <COMPUTED_HASH>が付与されます。
※ペイロードはmicroCMSがシークレット値とリクエストボディからSHA-256を使用したハッシュベースのHMACで生成します。

シークレット値はカスタム通知の設定画面で変更できます。
シークレット値には極力推測されづらい値を設定してください。(例: ruby -rsecurerandom -e 'puts SecureRandom.hex(20)' で生成した値)

Signatureの検証

以下2つの値を比較することで検証を行うことができ、リクエストがmicroCMSからのものであることを検証可能です。

  • X-MICROCMS-Signatureヘッダで受け取った値
  • ペイロード(request.body )と設定したシークレット値を元にした値

一例としてNode.jsの場合、検証は以下のような実装で行うことができます。

const crypto = require('crypto');

const expectedSignature = crypto
  .createHmac('sha256', <設定したシークレット>)
  .update(request.body)
  .digest('hex');
const signature = request.headers['X-MICROCMS-Signature'];
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
  throw new Error('Invalid signature.');
}

リクエスト内容

ヘッダ

リクエストヘッダには Content-Type: application/json が含まれます。
また、上述のシークレットを設定済みの場合は X-MICROCMS-Signature: <SIGNATUR_VALUE> が含まれます。

任意のリクエストヘッダーを追加することも可能です。カスタムリクエストヘッダー の「+」ボタンをクリックして追加してください。



informationInformation

リクエストヘッダ「X-MICROCMS-Signature」は、Webhookの種類によっては、「x-microcms-signature(全て小文字)」の表記で送信される場合がございます。
本ヘッダの処理にあたっては、大文字・小文字を区別しない形での実装をお願い申し上げます。

ボディ

リクエストボディには対象となったコンテンツやAPIの情報が含まれます。

{
  service: 'webhook-test',
  api: 'news',
  id: 'x2xkcwog9521',
  type: 'edit',
  contents: {
    old: {
      id: 'x2xkcwog9521',
      status: ['DRAFT'],
      draftKey: 'Vyf_XTclTY',
      publishValue: null,
      draftValue: {
        id: 'x2xkcwog9521',
        createdAt: '2021-06-02T05:56:24.513Z',
        updatedAt: '2021-06-02T06:05:09.601Z',
        publishedAt: '2021-06-02T06:05:09.601Z',
        revisedAt: '2021-06-02T06:05:09.601Z',
        title: 'タイトルです',
      },
    },
    new: {
      id: 'x2xkcwog9521',
      status: ['PUBLISH'],
      draftKey: null,
      publishValue: {
        id: 'x2xkcwog9521',
        createdAt: '2021-06-02T05:56:24.513Z',
        updatedAt: '2021-06-02T06:05:09.601Z',
        publishedAt: '2021-06-02T06:05:09.601Z',
        revisedAt: '2021-06-02T06:05:09.601Z',
        title: 'タイトルです',
      },
      draftValue: null,
    },
  },
}
  • service - 変更のあったコンテンツが属するサービスのサブドメインが入ります。
  • api - API作成時・更新時に指定したエンドポイントが入ります。
  • id - コンテンツのidが入ります。APIに関する操作の場合はnullが入ります。
  • type - 変更の種類です。新規追加時はnew、編集時はedit、削除時はdeleteが入ります。(コンテンツの公開ステータスの変更とは関係なく、データに対する変更の種類となります。)
  • contents - コンテンツ内容が入ります。APIに関する操作の場合はnullが入ります。
  • contents.old - コンテンツの編集前もしくは削除前の内容が含まれます。コンテンツの新規作成時にはnullが入ります。
  • contents.old.id - コンテンツの編集前もしくは削除前のコンテンツのidが含まれます。
  • contents.old.status - コンテンツの公開状態を配列で示します。公開中はPUBLISH、下書き中はDRAFTが含まれます。
  • contents.old.draftKey - コンテンツが下書き状態が含まれる場合に、管理画面で取得できる下書きキー(draftKey)が入ります。公開状態のみの場合はnullが入ります。
  • contents.old.publishValue - 公開状態のコンテンツをGET APIで取得した際のjsonデータが含まれます。
  • contents.old.draftValue - 下書き状態のコンテンツをGET APIで取得した際のjsonデータが含まれます。
  • contents.new - コンテンツの作成後もしくは編集後の内容が含まれます。コンテンツの削除時にはnullが入ります。
  • contents.new.id - コンテンツの作成後もしくは編集後のコンテンツのidが含まれます。
  • contents.new.status - コンテンツの公開状態を配列で示します。公開中はPUBLISH、下書き中はDRAFTが含まれます。
  • contents.new.draftKey - コンテンツが下書き状態が含まれる場合に、管理画面で取得できる下書きキー(draftKey)が入ります。公開状態のみの場合はnullが入ります。
  • contents.new.publishValue - 公開状態のコンテンツをGET APIで取得した際のjsonデータが含まれます。
  • contents.new.draftValue - 下書き状態のコンテンツをGET APIで取得した際のjsonデータが含まれます。

Webhookの動作確認およびデバッグについて

カスタム通知の動作確認およびデバッグの際には、「devhook」などのWebhookの検証ツールをご利用いただくと便利です。

ご利用の流れ

  1. カスタム通知の設定を追加する
  2. カスタム通知のURL欄にdevhookで取得したURLをコピーする
  3. 実際に管理画面上でトリガーとなる操作をおこない、devhook上でアウトプットを確認する

▼アウトプットのイメージ

cautionCaution

上記のような検証ツールはあくまで外部サービスですので、リクエストボディなどの情報は外部に共有されます。流出させてはいけないデータは使用しないなど、お取り扱いにはご注意ください。

Webhookの有効/無効設定

一時的にWebhookの設定を有効/無効にしたい場合は、Webhook一覧のスイッチを切り替えることで可能です。無効にした場合はWebhookが発行されなくなります。