Stripe webhook telemetry でイベントを送信して確認する
制御されたアプリケーション境界で Stripe webhook telemetry を使用し、イベント コントラクトを小さく保ち、集約ビューを構築する前に既知の結果を検証します。
- 1
結果を選択してください
Webhook のデバッグ
- 2
契約を定義する
provider_event_id、event_type、ライブモード、エンドポイント、および received_at
- 3
結果で発行する
イベント フィールドを信頼したりログに記録したりする前に、Stripe-Signature ヘッダーを確認し、署名や生の本文を Telemetry に送信しないでください。
- 4
証拠を検証する
Exercise a known fixture, then inspect webhook_processed for one correctly typed terminal row.
始める前に
始める前に
- 未変更のリクエスト本文に対して Stripe 署名を検証するサーバー エンドポイント
- Stripe イベント識別子をキーとする永続的な重複排除
- 低速なダウンストリーム作業を含む高速な承認パスが冪等ジョブに移動されました
配信設定
サーバー側のインストールと初期化
サーバー専用コードで telemetry-sh をインポートし、process.env.TELEMETRY_API_KEY で一度初期化します。 ブラウザ バンドル、クライアントに表示される環境変数、ソース管理、ログ、および例外メッセージに取り込み資格情報が含まれないようにします。
npmのインストール
npm install telemetry-sh- 1制限されたネットワーク動作を持つ再利用可能なサーバー側配信クライアントを 1 つ準備します。
- 2成功、失敗、再試行、またはタイムアウトの境界に結果イベントを追加します。
- 3アラートを有効にする前に、制御されたフィクスチャを送信し、保存されている行を検査します。
スニペット
1 つの構造化されたイベントから始める
ワークフローが完了、失敗、または再試行される場所にこの図形を追加します。次に、実際のフィールドからダッシュボードを構築します。
Stripe webhook telemetryイベント
await telemetry.log("webhook_processed", {
provider: "stripe",
provider_event_id: event.id,
event_type: "invoice.payment_succeeded",
status: "success",
latency_ms: 328,
downstream_job_count: 2,
idempotency_outcome: "new_event",
livemode: event.livemode,
});イベントスキーマ
provider_event_id、event_type、ライブモード、エンドポイント、および received_at
ステータス、status_code、latency_ms、試行、および idempotency_outcome
downstream_job、downstream_status、error_type、account_id、およびリリース
設定を確認する
チェックポイント 1
イベント フィールドを信頼したりログに記録したりする前に、Stripe-Signature ヘッダーを確認し、署名や生の本文を Telemetry に送信しないでください。
チェックポイント 2
重複した配送を重複した業務処理とは別に記録します。イベント識別子によって後者は不可能になるはずです。
チェックポイント 3
確認済みの配信を下流のジョブ結果に結び付けることで、素早い 2xx 応答によって失敗したサブスクリプションまたは請求書の作業が隠蔽されなくなります。
検証
イベントが到着したことを証明する
既知の成功例と失敗例を実行した後、これを実行します。最終的なイベント コントラクトがスニペットと異なる場合は、フォールバック テーブル名を置き換えます。
Stripe webhook telemetry 検証クエリ
SELECT *
FROM webhook_processed
ORDER BY timestamp_utc DESC
LIMIT 20;実装の参考資料
新しい運用パスを有効にする前に、イベント契約、データ安全性に関するガイダンス、上流の主要ドキュメントを確認してください。
イベントを記録する場所
結果イベントを小さく、回復可能なものに保つ
このパターンが提供するのは、
- 上流のワークフローの横にある、制限付きの SQL 対応の結果。
- ダッシュボード、アラート、およびイベント間の相関関係の安定したフィールド。
- 成功、失敗、再試行、タイムアウトの動作を検証するためのフィクスチャ駆動のパス。
このパターンでは提供されません
- OTLP エクスポーター、自動収集パイプライン、または詳細なトレースと診断ログの代替。
- ペイロードにイベント ID が含まれているという理由だけで、1 回だけ配信されます。
- 生のプロバイダー ペイロード、ユーザー コンテンツ、資格情報、または規制されたデータを収集する許可。
イベントスキーマの例
このワークフローのイベントスキーマ
クエリまたはスニペットを運用環境に適用する前に、行粒度、出力境界、必要なタイプ、プライバシー クラス、サンプル ペイロード、および検証チェックリストを確認してください。
関連製品の機能
このワークフローを続行します ダッシュボード
検証された製品または収益のクエリを、焦点を絞った意思決定の表面に変えます。
関連する SQL レシピ
その他のSQL例
このワークフローの構造化フィールドに対してクエリを実行し、結果の例を検査して、有用な回答をダッシュボードまたはアラートに変換します。
Webhook の再試行回復を測定する
Webhook の再試行により失敗が回復するのでしょうか、それとも追加の作業が発生しますか?
レシピを開くWebhook のレイテンシーと重複率を測定する
どの Webhook ソースが遅い、重複している、または信頼性が低いですか?
レシピを開く支払い失敗時の回復を測定する
どの支払い失敗が回復し、どのくらいの収益が依然としてリスクにさらされているのでしょうか?
レシピを開くWebhook のエンドツーエンドの完了を測定する
どの Webhook タイプがダウンストリーム作業を 5 分以内に完了しますか?
レシピを開く実装ファミリーごとに参照する
関連する統合パターンを比較する
この統合と組み合わせるテンプレート
さらなる統合