← Files microCMSARCHIVED FILE
skills/microcms-guide/references/webhooks.md
10.3 KB · Oct 2, 2026 · 00:33 UTC
# microCMS Webhook
最終確認: 2026-09-08
仕様の根拠は末尾の公式情報を参照する。設計上の推奨・コード例は本Skillの提案であり、唯一の公式推奨構成を意味しない。
## 目次
- [このリファレンスの役割](#このリファレンスの役割)
- [Webhookを使う場面](#webhookを使う場面)
- [通知種別を選ぶ](#通知種別を選ぶ)
- [通知タイミングを設計する](#通知タイミングを設計する)
- [カスタム通知を安全に受け取る](#カスタム通知を安全に受け取る)
- [署名を検証する](#署名を検証する)
- [ペイロードを扱う](#ペイロードを扱う)
- [失敗・重複・順序を前提に設計する](#失敗重複順序を前提に設計する)
- [キャッシュ更新に使う](#キャッシュ更新に使う)
- [トラブルシューティング](#トラブルシューティング)
- [実装時のチェックリスト](#実装時のチェックリスト)
- [公式情報](#公式情報)
## このリファレンスの役割
microCMSのコンテンツ変更を外部システムへ通知するWebhookについて、用途選択・セキュリティ・運用上の注意点をまとめる。
Webhookは「コンテンツが更新されたことを外部へ知らせる仕組み」であり、Webhook自体がサイトのキャッシュを更新したりビルドしたりするわけではない。受信先で必要な処理を実行する。
## Webhookを使う場面
代表的な用途:
- コンテンツ公開時にサイトを再ビルドする。
- ISRやアプリケーションキャッシュを再検証する。
- 外部検索インデックスを更新する。
- Slack等へ編集通知を送る。
- GitHub Actionsを起動する。
- 外部ワークフローを開始する。
ユーザーが「更新をすぐサイトへ反映したい」と言っている場合、まず利用中フレームワークのキャッシュ・再検証機構を確認し、そのトリガーとしてWebhookが必要か判断する。
## 通知種別を選ぶ
microCMSでは、用途に応じて複数のWebhook連携先が用意されている。
現在の代表的な種類:
- Slack
- Chatwork
- Netlify
- Cloudflare Pages
- Vercel
- AWS Amplify
- GitHub Actions
- メール通知
- カスタム通知
独自のAPIやRoute Handlerへ通知したい場合はカスタム通知を使う。
専用連携が用意されているサービスへ単純なビルド通知を送るだけなら、独自の受信APIを作る必要があるか検討する。
## 通知タイミングを設計する
Webhookは「何が起きたときに通知するか」を設定する。
代表例:
- コンテンツの公開・公開中コンテンツの更新
- 公開終了
- 下書き保存
- コンテンツ削除
- 下書き破棄
- API設定の変更
- API削除
公開サイトの更新だけが目的なら、下書き保存まで毎回再検証する必要があるか確認する。
逆に、プレビュー環境や検索インデックスなど、下書き状態にも反応させる必要がある場合は適切なタイミングを選ぶ。
Webhook通知を増やすほど受信側処理も増えるため、「通知できるものを全部ON」にしない。
## カスタム通知を安全に受け取る
カスタム通知では任意のURLへPOSTリクエストが送信される。
受信エンドポイントを単に公開し、届いたリクエストを無条件に信用しない。
基本方針:
1. Webhookのシークレットを設定する。
2. `x-microcms-signature` を検証する。
3. 検証前のリクエストで再ビルド・キャッシュ削除・データ更新などを実行しない。
4. 必要ならAPI・コンテンツID・イベント種別を追加で検証する。
5. 受信ログへDraft Keyやコンテンツ本文などを不用意に残さない。
## 署名を検証する
シークレットを設定したカスタム通知では `x-microcms-signature` ヘッダーが付与される。
署名は、設定したシークレットと**受信したリクエストボディ**からHMAC-SHA256で計算した値と比較する。
Node.jsでの概念例:
```ts
import crypto from 'node:crypto'
function verifySignature(rawBody: string, signature: string, secret: string) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex')
const actualBuffer = Buffer.from(signature)
const expectedBuffer = Buffer.from(expected)
return (
actualBuffer.length === expectedBuffer.length &&
crypto.timingSafeEqual(actualBuffer, expectedBuffer)
)
}
```
重要:
- JSONを一度parseして再serializeした文字列ではなく、署名計算の対象となった元のリクエストボディを使う。
- シークレットは環境変数などサーバー側で管理する。
- 単純な文字列比較より、可能ならタイミング攻撃を考慮した比較を使う。
フレームワークによってraw bodyの扱いが異なるため、専門Skillでその実装方法を確認する。
## ペイロードを扱う
カスタム通知のボディには、対象サービス・API・コンテンツID・変更種別・変更前後のコンテンツ情報などが含まれうる。
状態には `PUBLISH`、`DRAFT`、`CLOSED` などが含まれ、下書き状態が含まれる場合はDraft Keyがペイロードに入ることがある。
そのためWebhookペイロードを機密性のない単純なイベント通知として扱わない。
注意:
- 外部ログサービスへボディ全体を送る前に内容を確認する。
- 検証用Webhookサービスへ本番の機密コンテンツを送らない。
- 受信後の処理に本文が不要なら、必要なIDやイベント種別だけを使う。
## 失敗・重複・順序を前提に設計する
microCMSのWebhookでは、ネットワークエラーや4xx / 5xxで通知に失敗しても自動リトライは行われない。
また、操作の実行順に通知されることが基本でも、厳密な順序は保証されない。
複数コンテンツをまとめて操作した場合、対象コンテンツ数に応じて複数通知が送られる種類もある。
そのため受信側は次を意識する。
### 失敗への対応
Webhookが1回届くことだけを前提に、重要なデータ整合性を保証しない。
重要な同期処理なら、次のような補完を検討する。
- 定期的な差分・全件同期
- 手動再実行手段
- 受信失敗の監視
- キューを使った受信後処理
### 順序への対応
「公開通知の直後には必ず更新通知が来る」などの順序依存ロジックを避ける。
最新状態が必要なら、Webhookを「変更があった合図」として使い、受信後にContent APIから現在状態を取得する設計も検討する。
### 冪等性
同じコンテンツIDに対する処理が複数回走っても破綻しない設計を優先する。
## キャッシュ更新に使う
代表的な構成:
```text
microCMSで公開
↓
Webhook
↓
フロントエンドの受信API
↓
署名検証
↓
対象パス / タグを再検証
```
キャッシュ更新では、Webhookを受けた瞬間にサイト全体を毎回再ビルドする方法だけを選ばない。
フレームワークがOn-demand Revalidationを提供しているなら、変更対象だけを更新できるか検討する。
たとえば記事詳細の変更で影響する可能性があるのは:
- `/articles/{id}`
- `/articles`
- カテゴリ一覧
- タグ一覧
- トップページの記事一覧
など。
どこを無効化するかは、API構造ではなく「そのコンテンツをどのページが利用しているか」で決める。
Next.jsの `revalidatePath` / `revalidateTag` などは `microcms-nextjs` で扱う。
## トラブルシューティング
### Webhookが届かない
確認する:
1. Webhook設定が有効か。
2. 対象イベントが通知タイミングに含まれているか。
3. 送信先URLが外部から到達可能か。
4. 受信側が4xx / 5xxを返していないか。
5. 署名検証で失敗していないか。
失敗時に自動リトライされないため、一度の失敗を「そのうち再送される」と考えない。
公式ヘルプの確認時点では、microCMS側でWebhook通知ログを閲覧する機能は提供されていない。利用者へ存在しないログ画面を案内せず、対象API・通知イベント・有効設定を確認したうえで受信先のアクセスログと処理ログを使う。未到達と受信後失敗を分ける。[通知ログの提供状況](https://help.microcms.io/ja/knowledge/webhook-request-logs)、[Webhookの切り分け](https://help.microcms.io/ja/knowledge/webhook-failed)
### Webhookは届くがサイトが更新されない
Webhook受信とキャッシュ更新を分けて確認する。
1. 受信ログがあるか。
2. 署名検証を通っているか。
3. 正しいコンテンツID / APIを解析できているか。
4. 正しいパス・タグを再検証しているか。
5. 再検証後の次リクエストで更新される仕様ではないか。
6. ホスティング側に別のキャッシュ層がないか。
### 通知数が多い
- 下書き保存まで通知対象にしていないか。
- 一括操作でコンテンツ数分の通知が発生していないか。
- 受信側で同一コンテンツの短時間イベントをまとめる必要があるか。
## 実装時のチェックリスト
- Webhookを使う目的が明確か。
- 必要な通知タイミングだけを有効にしているか。
- カスタム通知ではシークレットを設定しているか。
- `x-microcms-signature` を検証しているか。
- Draft Key等をログへ残していないか。
- 4xx / 5xx時に自動リトライされないことを考慮しているか。
- 通知順序へ依存していないか。
- 受信後処理が可能な範囲で冪等か。
- サイト全体ではなく必要な範囲だけを更新できないか検討したか。
- フレームワーク固有の再検証処理は対応する専門Skillへ委ねているか。
## 公式情報
- [コンテンツのWebhook：署名・ペイロード・再送・順序](https://document.microcms.io/manual/webhook-setting)
SHA-256: c36e9a684d9a10f16fbc78a81aa8ca5f1ede013fc81aed7b63bfeffe9c734223