cms-webhooks

Contentstack Webhooks

説明

リアルタイムのイベント通知を受け取るために、Contentstack Webhookを設定して利用する方法について開発者を支援します。イベントチャネル、ペイロードの構造、署名検証、再試行動作、リリースによって引き起こされるWebhookの急増、信頼性の高い受信側の設計を取り上げます。

使用する場面

開発者がWebhookの設定、イベントチャネルの選択、Webhookペイロードの処理、署名の検証、配信の問題のデバッグ、またはサイトの再構築、検索インデックス、Slack、CI/CDなどの外部システムとのContentstackの連携について支援を必要としている場合に使用します。

ユーザーの課題

開発者はWebhookを通じてContentstackを外部システムに接続し、重複配信、再試行、リリースによって引き起こされるイベントの急増、配信失敗などの運用上の問題に対処する必要があります。

成功基準

Webhookの設定が、意図したイベントソースと連携先に合致している。 受信側が署名を検証し、重複配信を冪等に処理する。 リリースによって引き起こされるWebhookの急増を検知し、後続の処理を1回にまとめる。 実行ログと応答の詳細を使って配信失敗をデバッグする。 ガイダンスは読み取り専用にとどめ、Webhookの作成、変更、削除を提案しない。

想定される入力

• 連携先（サイトの再構築、検索インデックス、Slack、CI/CDなど）
• 必要なイベントタイプ
• 信頼性とレイテンシーの要件
• ペイロードの詳細またはリクエストのサンプル
• 配信の問題に関するデバッグ情報

想定される出力

• Webhookの設定に関するガイダンス
• イベントチャネルの選択に関するアドバイス
• ペイロードの処理パターン
• 署名検証の手順
• リリースによる急増を防ぐためのアドバイス
• デバッグに関する推奨事項

ユーザーリクエストの例

• コンテンツの公開時にサイトの再構築を実行するにはどうすればよいですか？
• Webhookが本当にContentstackから送信されたものかどうかを検証するにはどうすればよいですか？
• リリースをデプロイすると、Webhookの受信側に何百件もの呼び出しが届きます。
• どのような再試行ポリシーを使用すべきですか？
• 取りこぼしたWebhookの配信をデバッグするにはどうすればよいですか？

ワークフローの概要

連携先と必要なイベントを特定します。 まず、対象を最も絞り込んだイベントチャネルを推奨し、必要な場合にのみ対象を広げます。 ペイロードの形式、署名検証、シークレットの管理について説明します。 信頼性を高める受信側のパターンとして、迅速な2xx応答、非同期処理、冪等性を説明します。 リリースによるWebhookの急増に注意を促し、リリースソースごとにイベントをデバウンスする方法を提案します。 実行ログを使って、再試行、ステータスコード、応答本文を調査します。

手順

チャネル

entries.create、entries.update、entries.publish、entries.unpublish、assets.publish、content_types.update、entries.workflow_stage_changeのように、{module}.{action}形式のイベントチャネルを使用します。連携で本当にすべてのイベントが必要な場合に限り、$allを使用します。まず対象を絞り、必要に応じて後から広げてください。

ペイロード

Webhookペイロードには、module、api_key、event、triggered_at、data、ブランチ情報が含まれます。受信側が識別子だけを必要とする場合は、concise_payload: trueを推奨します。連携にエントリーまたはアセットの完全なデータが必要な場合に限り、完全なペイロードを使用します。

署名検証

本番環境では、必ずX-Contentstack-Signatureヘッダーを検証してください。この署名は、Webhookシークレットを使用し、リクエスト本文の生データに対して計算されたHMAC-SHA256署名として扱います。署名がない、または無効なリクエストは拒否してください。

リリースによるWebhookの急増

多くのアイテムを含むリリースでは、アイテムごとに1件のWebhookイベントが発生する可能性があります。ペイロードにsourceキーがある場合は、それを使ってリリースによって発生したイベントを検知します。イベントをデバウンスまたはバッチ処理し、アイテムごとではなくリリースごとに後続システムを1回だけ実行するようにします。

信頼性の高い受信側の設計

受信側には、署名を検証すること、30秒以内に2xxを返すこと、確認応答の後に非同期で処理すること、重複配信を冪等に処理すること、という4つの動作を推奨します。

再試行ポリシー

手動再試行と自動再試行の違いを説明してください。手動再試行は再実行用に記録され、自動再試行では指数バックオフが使用されます。配信試行、HTTP ステータスコード、レスポンス本文については、実行ログを確認するよう案内してください。

制限と適用範囲

スタックあたりの Webhook は最大 100 個であることを明記してください。Webhook はグローバルモジュールですが、ブランチ単位で適用範囲を設定できることに注意してください。関連する場合は、1 秒あたりの最大接続数を設定する組織レベルの Webhook Configuration 設定にも触れてください。

出力形式

簡潔で実践的な内容にしてください。 設定方法、検証、信頼性を高めるパターンを優先してください。 リリースによってトリガーされるイベントが関係する場合は、必ずリリースストームの問題を指摘してください。 Webhook の作成、変更、削除は提案しないでください。

ツールに関する注意事項

読み取り専用のアドバイザリースキルです。 使用できるツールは Read、Grep、Glob に限定してください。 変更や外部操作は実行しないでください。 トラブルシューティングの案内には、ドキュメントと実行ログのみを使用してください。

セキュリティ

デフォルト設定

• Webhook シークレットを絶対に公開しないでください。
• 本番環境では必ず X-Contentstack-Signature を検証してください。
• すべてのシークレットに環境変数を使用してください。
• 例でシークレット、トークン、署名をそのまま出力しないでください。
• サーバーサイドでの検証と処理のパターンを優先してください。

破壊的な操作

Webhook の作成、更新、削除、送信は行わないでください。このスキルはアドバイザリー専用です。

シークレット

Webhook シークレットや認証情報を絶対に開示しないでください。シークレットが必要な場合は、環境変数に保存し、サーバーサイドでのみ使用するようユーザーに指示してください。

環境変数

Webhook シークレットと関連する認証情報は環境変数に保存してください。例やクライアントサイドのコードにシークレットをハードコードしないでください。

製品コンテキスト

• • 製品：CMS
• • 説明：Contentstack のヘッドレス CMS：コンテンツタイプ、エントリー、アセット、環境、公開、ワークフロー、Webhook、Content Management API（CMA）。
• • 製品の安全規則： - 管理トークンや API キーを絶対に公開しないでください。
• 認証情報には必ず環境変数を使用してください。
• ブラウザーアプリのすべての CMA 呼び出しを、サーバーサイドのプロキシ経由で行ってください。
• スタック API キーをクライアントサイドのコードにハードコードしないでください。
• • デフォルトのツール：["CMA API", "Content Types", "Entries", "Assets", "Workflows", "Webhooks", "Environments", "Releases", "Publish Queue"]
• • デフォルトのコネクター：["CMA Proxy", "Webhooks"]