安全な応答デバッグのための Webhook 配信ログ フィールド
有用な配信スキーマは、試行フィールドを正規化し、最終ステータス コードと制限付き応答メタデータを保持し、URL、要求ヘッダー、承認、ペイロード、生の応答コンテンツを除外します。
- 1
配送終了
ログ行ごとに 1 回ではなく、成功または永続的な再試行が終了した後に 1 回発行します。
- 2
フィールドは正規化されています
attempt_number などのソース フィールドを attempt_count にマップし、status_code、response_body_bytes、および未加工の response_body の代わりにホワイトリストに登録されたコンテンツ タイプを保持します。
- 3
秘密は外に出さない
request_headers、認証値、顧客 URL、または Webhook ペイロードは決して保存しないでください。
- 4
回復が測定される
永続的な障害、繰り返し発生するステータス コード、および再試行後の回復を宛先タイプごとに比較します。
穀物
論理 Webhook 配信ごとに 1 つのターミナル結果。
オーナー
Webhook配信者
いつ発行するか
成功後、または永続的な再試行が枯渇した後。
フィールド契約
フィールドの型と除外するデータ
運用クエリが既存のフィールド名とタイプに依存した後も、既存のフィールド名とタイプを安定した状態に保ちます。オプションのコンテキストは、特定の決定によって制限され、文書化され、正当化されたままにする必要があります。
| フィールド | 種類 | 必須 | プライバシー | 意味 |
|---|---|---|---|---|
| timestamp_utc | timestamp | yes | non-sensitive | 結果境界の UTC 時間。 |
| event_id | string | yes | non-sensitive | 重複排除に使用される安定した一意の識別子。 |
| release | string | yes | non-sensitive | イベントを発行したアプリケーションまたはサービスのバージョン。 |
| account_id | string | yes | pseudonymous | 安定した内部アカウント識別子。電子メールや名前ではありません。 |
| delivery_id | string | yes | pseudonymous | 安定した論理配信識別子。 |
| destination_type | string | yes | non-sensitive | 宛先 URL ではなく、限定された統合カテゴリ。 |
| attempt_count | number | yes | non-sensitive | 最終的な結果を試行します。 |
| status_code | number | no | non-sensitive | 応答が存在する場合の最終的な HTTP ステータス。 |
| response_body_bytes | number | no | non-sensitive | 最終的なレスポンスボディのサイズ (バイト単位)。応答本文の代わりにサイズを保存します。 |
| response_content_type | string | no | review | application/json などのホワイトリストに登録された応答メディア タイプ。無制限の応答ヘッダーをコピーしないでください。 |
| status | string | yes | non-sensitive | 配信されたか、永久に失敗しました。 |
合成 JSON イベント
{
"timestamp_utc": "2026-07-28T14:29:08Z",
"event_id": "evt_webhook_01",
"account_id": "acct_8f31",
"release": "2026.07.2",
"delivery_id": "delivery_09cc",
"destination_type": "slack",
"attempt_count": 1,
"status_code": 200,
"response_body_bytes": 27,
"response_content_type": "application/json",
"status": "delivered"
}プライバシーのレビュー
取り込む前に識別子を確認する
この例では合成識別子を使用します。仮名の値も個人データである可能性があり、レビュー フィールドによってビジネスまたはプロバイダーのコンテキストが公開される可能性があります。独自の同意、保持、アクセス、常駐、および削除の要件を適用します。
account_id: pseudonymousdelivery_id: pseudonymousresponse_content_type: review
検証チェックリスト
ダッシュボードを構築する前に契約を証明する
- Send one known webhook_delivery_completed fixture after the documented outcome boundary.
- Verify all 8 required fields arrive with the documented types.
- 同じイベント識別子を再試行し、選択した重複排除動作を確認します。
- ワークフローがサポートしている場合は、制御された失敗または代替結果を送信します。
- 関連する SQL を固定ウィンドウで実行し、結果をフィクスチャと照合します。
よくある間違い
1 つの行を 1 つの永続的な結果と等しく保つ
- Emitting webhook_delivery_completed before webhook delivery worker knows the final outcome.
- 1 つのテーブルに複数の穀物を混ぜると、個数と割合が曖昧になります。
- 制御されたカテゴリを生の URL、ペイロード、プロンプト、またはエラー テキストに置き換えます。
- 保存されたクエリとダッシュボードがフィールド タイプに依存した後、その場でフィールド タイプを変更します。
- 文書化された調査、アクセス、保持の必要がない識別子の追加。
契約書を利用する
イベントをクエリして操作可能にする
関連契約
本番トラフィックの前にテストイベントを送る
ライブ ワークフローに接続する前に、無料の API キーを作成し、合成イベントを送信し、推論されたテーブルを検査します。