Stripe Webhook サブスクリプション同期完全ガイド：TG-Staff 支払いコールバック、プラン有効化、更新・キャンセル処理

Telegram Bot をカスタマーサポートや運用に使用するチームにとって、サブスクリプション管理は SaaS 製品の中核です。ユーザーが支払いを完了した後、プランはいつ有効になるのでしょうか？更新が失敗した場合、機能はすぐに低下するのでしょうか？サブスクリプションをキャンセルした後、データは失われるのでしょうか？これらの問題を手動で支払いステータスを確認する方法に依存すると、効率が悪いだけでなく、エラーが発生しやすくなります。TG-Staff は Stripe Webhook サブスクリプション同期 メカニズムを統合することで、支払い成功からプラン有効化までの完全自動化ループを実現しました。この記事では、技術アーキテクチャ、イベントコールバックロジックからエッジケースの処理までを解説し、プロセスを完全に理解できるようにします。

---

Stripe Webhook が TG-Staff のサブスクリプション管理に不可欠な理由

Stripe Webhook の本質はリアルタイムイベント通知です。ユーザーが Stripe Checkout で支払いを完了したり、更新が成功したり、サブスクリプションをキャンセルしたりすると、Stripe は TG-Staff の事前設定されたエンドポイントに完全なイベントデータを含む HTTP POST リクエストを送信します。TG-Staff はデータを解析・検証した後、直ちにユーザーのプランステータスを更新します。

このメカニズムは、2つの一般的な問題を解決します：

• 手動確認：運用担当者が Stripe Dashboard にログインして支払い記録を確認し、TG-Staff コンソールに戻って手動でプランをアップグレードする必要がありません。
• 遅延有効化：従来のポーリング方式では、数分ごとにしか支払いステータスを確認できず、ユーザーが支払い後も高度な機能を使用するまで待たされる可能性がありました。Webhook コールバックは通常 1～3 秒以内に同期を完了します。

チームにとって、これは プラン有効化、更新延長、キャンセルによるダウングレード という3つの重要なアクションを Stripe Webhook に自動処理させることができ、カスタマーサポートの負荷を減らし、ユーザーエクスペリエンスを向上させることを意味します。

---

TG-Staff サブスクリプション同期の全体アーキテクチャ

同期チェーン全体は、支払い開始、Webhook コールバック、プラン更新の3つのフェーズで構成されます。これら3つのステップ間の相互作用を理解することで、同期の問題をトラブルシューティングしたり、支払いフローをカスタマイズしたりするのに役立ちます。

支払い開始フェーズ：Stripe Checkout とセッション作成

ユーザーが TG-Staff コンソールの「マイサブスクリプション」ページでプラン期間（30/90/180/360日）を選択し、「Stripe 支払い」ボタンをクリックします。TG-Staff バックエンドは Stripe API を呼び出して Checkout Session を作成し、以下の主要パラメータを含めます：

• success_url：支払い成功後に TG-Staff コンソールにリダイレクト
• cancel_url：支払いキャンセル後にプラン選択ページにリダイレクト
• metadata：ユーザーID、プランタイプ、期間などのカスタムフィールドを含み、コールバック時にユーザーを識別

ユーザーが Stripe 支払いフォーム（クレジットカード、Google Pay、Apple Pay など）を完了すると、Stripe はユーザーを success_url にリダイレクトします。この時点でフロントエンドは「支払い成功、プランを同期中…」と表示しますが、バックエンドの同期はまだ完了していません。実際のプラン更新は Webhook コールバックに依存します。

コールバックフェーズ：Webhook イベントタイプと TG-Staff のリスニングロジック

Stripe は TG-Staff の事前設定された Webhook エンドポイントにイベントを送信します。TG-Staff がリッスンする主要イベントは次のとおりです：

イベントタイプ	トリガーシナリオ	同期アクション
checkout.session.completed	ユーザーの初回支払いまたは更新成功	署名を検証し、subscription ID、期間、ユーザーIDを抽出し、プランステータスを更新
invoice.payment_succeeded	自動更新成功（例：月払いの期限到来時の引き落とし）	プランの有効期限を延長し、機能を維持
customer.subscription.updated	プラン変更（アップグレード、ダウングレード、期間調整）	プランレベルと期間を更新
customer.subscription.deleted	ユーザーによるサブスクリプションキャンセル、または Stripe による自動キャンセル（例：支払い失敗が長期化）	プランの有効期限をマークし、現在の期間内は機能を維持

TG-Staff はイベントを受信すると、まず Stripe 署名を検証し（Webhook Secret を使用）、偽造コールバックを防止します。検証が成功すると、イベントデータ内の metadata フィールドを解析し、TG-Staff 内部のユーザーID と照合して、データベースのプランレコードを更新します。

同期完了：コンソールの「マイサブスクリプション」ページでのプランステータスのリアルタイム更新

更新が成功すると、TG-Staff コンソールの「マイサブスクリプション」ページには新しいプラン情報がリアルタイムで表示されます：プラン名、有効期限、エージェント数、利用可能な機能（例：分流リンク、コンテンツ管理など）。ユーザーはページをリフレッシュしなくても（WebSocket またはポーリングメカニズムにより）変更を確認できます。

---

支払い成功コールバック：プラン即時有効化の処理ロジック

checkout.session.completed は最も重要なイベントです。TG-Staff がこのイベントを処理する詳細な流れは以下の通りです。

イベント検証とデータ抽出

1. 署名検証：TG-Staff は Stripe Webhook Secret を使用してリクエストヘッダー stripe-signature を検証します。署名が一致しない場合は 400 ステータスコードを返し、エラーログを記録します。
2. データ抽出：イベント data.object から以下を取得します：
   • subscription：Stripe サブスクリプション ID
   • metadata.user_id：TG-Staff 内部ユーザー識別子
   • metadata.plan：プランタイプ（standard / pro）
   • metadata.period：期間日数（30 / 90 / 180 / 360）
3. 冪等性チェック：同一イベントがネットワーク再試行により複数回配信される可能性があります。TG-Staff はイベント ID を使用して重複を排除し、プランステータスが一度だけ更新されるようにします。

プラン権限マッピングと有効化

データ抽出後、TG-Staff はプランタイプと期間に基づいてユーザー権限テーブルを更新します：

• エージェント枠：スタンダード版は 3 つ、プロフェッショナル版は 5 つ、より長い期間では追加のエージェントが含まれる場合があります（公式サイトのプランページを参照）。
• 機能スイッチ：スタンダード版では分流リンク、会話分流、AI 翻訳（クォータあり）を有効化；プロフェッショナル版ではさらにコンテンツモデレーション、無制限翻訳、ユーザープロファイル、TG テーマチャット背景を有効化。
• 有効期限：現在時刻 + 期間日数。例：ユーザーが 90 日間のプロフェッショナル版を購入した場合、有効期限は現在時刻 + 90 日となります。

同時に、TG-Staff は Stripe サブスクリプション ID をユーザーレコードに関連付け、後続の更新やキャンセルイベントのマッチングに使用します。

コールバック失敗の再試行メカニズムとログ調査

TG-Staff がコールバック処理中に一時的なエラー（データベースタイムアウト、ネットワーク変動など）に遭遇した場合、5xx ステータスコードを返します。Stripe には組み込みの再試行メカニズムがあります：初回失敗後 5 分待機、2 回目は 10 分、3 回目は 30 分、最大 3 回再試行します。

3 回の再試行がすべて失敗した場合、Stripe は Dashboard の Webhook ログで「失敗」とマークします。この場合、ユーザーは TG-Staff コンソールの「マイサブスクリプション」ページで手動で「ステータス同期」ボタンをクリックし、強制チェックをトリガーできます。それでも解決しない場合は、@tgstaff_robot テクニカルサポートに連絡してください。

---

更新とキャンセル：Stripe Webhook 同期の境界シナリオ

初回支払い以外にも、日常運用では更新成功やサブスクリプションキャンセルがよく発生します。TG-Staff は異なるイベントで区別して処理します。

更新成功：期間延長と機能維持

Stripe が自動引き落としで更新に成功した場合、invoice.payment_succeeded イベントがトリガーされます。TG-Staff のロジックは以下の通りです：

• subscription に関連付けられた TG-Staff ユーザーを取得
• 現在のプラン有効期限を確認し、1 期間延長（例：月払いの場合は 30 日延長）
• 機能権限は変更なし：エージェント枠、分流リンク、翻訳クォータなどはすべて既存の設定を維持

このプロセスは完全に自動化されており、ユーザーの操作は不要です。更新が失敗した場合（例：クレジットカードの期限切れ）、Stripe は invoice.payment_failed イベントを送信します。TG-Staff は即座にダウングレードせず、Stripe の自動再試行（通常 3～5 回、数日間隔）を待ちます。最終的に失敗した場合、Stripe は customer.subscription.deleted イベントを送信します。

サブスクリプションキャンセル：プラン期限前のダウングレード通知とデータ保持ポリシー

ユーザーが Stripe Billing Portal またはカスタマーサポートを通じてサブスクリプションをキャンセルすると、Stripe は customer.subscription.deleted イベントを送信します。TG-Staff の処理ポリシーは以下の通りです：

• 有効期限をマーク：キャンセル後もプラン有効期限は変わりません（現在の支払いサイクルの終了日）。
• 機能維持：サイクル終了までは、ユーザーは購入済みの全機能（エージェント、分流リンク、コンテンツモデレーションなど）を引き続き使用できます。
• ダウングレードトリガー：サイクル終了後、プランは自動的に無料版にダウングレードされます（エージェント枠なし、分流リンクなし、翻訳クォータゼロ）。ただし、ユーザーデータ（会話履歴、ユーザープロファイル、Bot 設定）は削除されず、無料枠を超える機能のみが制限されます。

例えば、ユーザーが90日間のプロフェッショナル版を購入し、30日目にサブスクリプションをキャンセルした場合、残りの60日間は機能が完全に利用可能です。90日目に期限が切れると、エージェント数は5から0に減少し、分流リンク機能は無効になりますが、過去の会話履歴は引き続きコンソールで確認できます。

---

USDTオンチェーン支払いとStripeの二重チャネルにおける同期の違い

TG-StaffはUSDT（TRC20）オンチェーン支払いとStripe支払いの両方をサポートしていますが、両者の同期メカニズムには大きな違いがあります。

比較項目	Stripe支払い	USDTオンチェーン支払い
コールバックトリガー	Stripe Webhookによるリアルタイムプッシュ	自動イベントプッシュなし
確認時間	支払い完了と同時にコールバック（1〜3秒）	ブロックチェーン確認数に依存（通常1〜3分）
同期方法	自動、手動操作不要	ユーザーが手動でコンソールにトランザクションハッシュを送信するか、TG-Staffのバックグラウンドスキャンを待つ
障害処理	Stripeが自動で3回リトライ	カスタマーサポートに連絡し、チェーン上の記録を手動で確認する必要がある

Stripe Webhookの自動化の利点は明らかです。支払い成功 → プランが即時有効になり、ユーザーの追加操作は不要です。一方、USDT支払いはユーザーが手動でトランザクションハッシュを送信する必要があり、TG-Staffのバックグラウンドスキャンで確認後にプランが更新されるため、リアルタイム性が低くなります。高度な機能を迅速に有効化する必要があるチームには、Stripe支払いを優先的に推奨します。

---

デバッグとトラブルシューティング：Webhook同期失敗の一般的な原因

Stripe Webhookのメカニズムは成熟していますが、設定やネットワークの問題により同期が失敗することがあります。以下に典型的な問題と調査手順を示します。

1. Webhook署名検証失敗：Stripe DashboardでWebhookエンドポイントに設定したSecretがTG-Staffの要求と一致しない。解決策：Stripe Dashboard → Developers → Webhooks → エンドポイントをクリック → Signing secretをコピーし、TG-Staffコンソールの該当設定項目に貼り付けます。

2. ネットワークファイアウォールによるブロック：TG-StaffサーバーのIPがファイアウォールやCDNルールによってブロックされ、Stripeが接続できない。解決策：サーバーのセキュリティグループがStripeのIP範囲（詳細はStripe公式ドキュメント参照）を許可しているか確認します。

3. イベントタイプが有効化されていない：Stripe Webhookエンドポイントはデフォルトで一部のイベントのみをリッスンします。checkout.session.completedにチェックが入っていない場合、支払い成功のコールバックを受信できません。解決策：Stripe DashboardのWebhookエンドポイント設定で、必要なイベントタイプを追加します。

4. 重複イベントによる冪等性の異常：Stripeがネットワーク再試行により同じイベントを複数回配信する可能性があります。TG-StaffのイベントID重複排除メカニズムは通常処理できますが、重複排除キャッシュが期限切れの場合、プランステータスが誤って上書きされる可能性があります。解決策：TG-Staffのログでevent_idの重複レコードを確認し、テクニカルサポートに連絡してキャッシュをクリアします。

---

よくある質問

Q: Stripe Webhookのコールバック後、プランがすぐに反映されない場合はどうすればよいですか？

A: Stripe DashboardでWebhookエンドポイントが正しく設定されているか確認し、checkout.session.completedイベントが有効になっていることを確認してください。TG-Staffはコールバックを受け取ってから通常1〜3秒以内にプランステータスを同期します。30秒以上経っても反映されない場合は、TG-Staffコンソールの「マイサブスクリプション」ページにエラーメッセージがないか確認するか、@tgstaff_robotのテクニカルサポートにお問い合わせください。

Q: USDTで支払った場合、Stripe Webhookはトリガーされますか？

A: されません。USDTのチェーン上での支払いはStripeを経由しないため、Stripe Webhookはトリガーされません。TG-Staffは独立したチェーン上の取引確認ロジックでUSDT支払いを処理し、確認時間はブロックチェーンネットワークの承認数に依存します（通常1〜3分）。Stripeのコールバックとはリアルタイム性が異なります。

Q: サブスクリプションをキャンセルした場合、Webhookはすぐに同期されますか？データは失われますか？

A: はい。customer.subscription.deletedイベントは即座にTG-Staffにコールバックされますが、プラン機能は現在の支払い期間が終了した後にのみダウングレードされます。期間中のデータ（会話履歴、ユーザープロファイルなど）は失われません。ダウングレード後は、プラン上限を超える機能（例：エージェント数超過時に新規会話が割り当てられない）のみが制限されます。期限前にBilling Portalからサブスクリプションを復元することをお勧めします。

Q: Stripe Webhookのコールバックが失敗した場合、TG-Staffにリトライメカニズムはありますか？

A: あります。Stripeには自動リトライメカニズム（最大3回、間隔は増加）が組み込まれています。TG-Staff側でもコールバックログを記録し、連続して失敗した場合、ユーザーはコンソールの「マイサブスクリプション」ページから手動で同期をトリガーするか、@tgstaff_robotに連絡して手動で修正できます。一般的な失敗原因には、ネットワークファイアウォールによるブロック、Webhook署名の期限切れ（Secretを定期的に更新する必要があります）などがあります。

Q: 複数のStripeアカウント（複数プロジェクト・複数マーチャントなど）のWebhook同期はサポートされていますか？

A: 現在、TG-Staffは単一のStripeアカウントのWebhook設定をサポートしており、複数のTelegram Botプロジェクトを一元管理するのに適しています。複数マーチャントで支払いを分離する必要がある場合は、Stripe Connectまたはアカウント分割方式を提案し、TG-Staffチームにカスタマイズ対応についてご相談ください。

---

Stripe Webhook自動同期によるサブスクリプション管理を体験してみませんか？

TG-Staffに登録して3日間無料トライアル。Webhookサーバーを自前で構築することなく、支払いコールバック、プラン即時反映、更新・キャンセルの自動処理の完全なフローを体験できます。

• 無料トライアルに登録：https://app.tg-staff.com/
• Webhook設定ドキュメントを参照：https://docs.tg-staff.com/
• テクニカルサポートに連絡：@tgstaff_robot