commet-webhooks

Commet Webhook

インストール済み SDK を Webhook の契約として使用します。このスキルでは処理ワークフローを定義しますが、現在のイベント一覧は定義しません。

契約を確認する

1. 言語、フレームワーク、インストール済みの Commet SDK、連携パッケージ、明示的に固定された Webhook API バージョンを特定します。
2. パッケージマネージャーを使用して、インストール済み SDK の docs/manifest.json を探します。マニフェストのエントリーポイント、生成された Webhook リファレンス、およびタスクに必要な正確なイベントのエントリーのみを読みます。
3. ハンドラーヘルパーやペイロードの形式を選択する前に、生成された Webhook 型とインストール済みフレームワークパッケージの README を読みます。
4. Node プロジェクトでは、commet doctor --output agent を実行し、ドキュメント、互換性、API バージョン、またはプロジェクトコンテキストのチェックで失敗した項目を解決します。

このスキルから、イベントのユニオン型、ペイロードのエンベロープ、ヘッダー、再試行スケジュール、コールバック名をコピーしないでください。インストール済みのドキュメントや型に記載されていない場合は、推測せず、不足している契約を報告してください。

エンドポイントを実装する

1. インストール済みのフレームワークヘルパーがある場合はそれを使用し、ない場合はインストール済み SDK の raw body 検証方法に従います。
2. ペイロードを解析または処理する前に、変更されていないリクエストボディを使って署名を検証します。
3. 生成された正確なイベント型で絞り込み、不明なイベントはインストール済みドキュメントに従って処理します。
4. インストール済みの契約で公開される永続的なイベント ID を使用して、業務処理を冪等にします。
5. 障害復旧のために再配信が必要な場合は、確認応答を返す前に永続的な処理を完了します。意図的に非同期にする処理は、永続キューに保持します。
6. アクセス制御と現在のサブスクリプションに関する判断は、Commet に直接問い合わせます。Webhook は、メール送信、プロビジョニング、分析、外部同期などのバックグラウンド処理に使用します。
7. ユーザーがバージョン移行を許可するまで、エンドポイントに明示的に設定された Webhook バージョンを維持します。

副作用を制御する

ローカルハンドラーの編集とテストはローカル作業です。エンドポイントの登録、プロバイダーのテストイベント送信、配信の再実行、Webhook 設定の変更はリモートでの副作用です。

リモートでの副作用を発生させる前に、対象の組織と sandbox または live モードを明示します。Node プロジェクトでは、PROJECT_CONTEXT_VALID の doctor チェックに合格していることを確認します。それ以外の場合は、プロジェクトまたはユーザーのコンテキストを明示的に確認します。明示的な許可なしに、live イベントを送信または再実行しないでください。

Webhook シークレット、署名、認証ヘッダー、または顧客データを含むペイロード全体をログに記録しないでください。

検証する

インストール済みの署名ヘルパーまたは実際の sandbox 配信を使って、公開ハンドラーの境界をテストします。有効な署名、無効な署名、要求されたイベント、重複配信、ハンドラーの確認応答動作を網羅します。リポジトリのフォーマッター、コンパイラーまたは型チェック、および関連テストを実行します。