Zenn
💥

Firebase × Stripe 拡張で Webhook が動かない!? 〜APIバージョンの罠と解決まで〜

に公開
Firebase
Stripe
決済
tech

はじめに

Firebase の拡張機能「firestore-stripe-payments」は、Firestore と、決済プラットフォーム Stripe を簡単に連携できる強力なツールです。

特にサブスクリプション管理が自動化されて非常に便利なのですが、Stripe API バージョンの非互換によって、請求書に関する処理が失敗するという問題に直面しました。

この記事では、Webhook が失敗し invoice が作成されない問題とその解決策を共有します。

発生した問題

  • Stripe で支払いは完了している（カード決済済み）
  • しかし Firestore に invoices コレクションが作成されない
  • Webhook ログに以下のようなエラーが出力される
Error: Webhook handler failed. View function logs in Firebase.
Value for argument "documentPath" is not a valid resource path.

テスト環境では正常動作 → 原因の特定
テスト用の Firebase プロジェクトと Stripe アカウントでは正常に動作。

そこで、本番とテストの差分を洗い出すと…

Firebase 拡張バージョン：同一

Firestore のセキュリティルール：問題なし

Stripe の API バージョン：異なる！

APIバージョンは変更できない

一度アップグレードするとアカウントのAPIバージョンは変更できません、今回は最新版（2025-05-28.basil）に更新してしまいましたので、ダウングレードできませんでした。次にのべますが、公式にダウングレードできないか問い合わせましたが、これは無理でした。

ダッシュボードからは実質 API バージョンを変更できない件と Stripe 公式の回答

今回、本番環境で Firebase の Stripe 拡張を用いた決済処理中にエラーが発生し、テスト環境では成功するにもかかわらず本番環境で失敗する原因を調査したところ、使用している Stripe API バージョンが異なることに気づきました。

  • テスト環境：2025-01-27.acacia
  • 本番環境：2025-05-28.basil

本番環境の API バージョンをテスト環境と揃えようと Stripe に問い合わせたところ、以下のような回答を得ました：

アカウントレベルで適用されている API バージョンのダウングレードはできかねております。

つまり、一度本番アカウントに適用された API バージョンは、ダウングレードできない仕様になっています。

ただし代替策として：

  • API リクエストごとにヘッダーで API バージョンを上書きできる（Versioning）
  • Webhook エンドポイントごとに個別に API バージョンを指定可能

といった方法は提供されています。詳細は以下の公式ドキュメントを参照すると良いです：

と教えてもらいました。

さて、API呼び出しでバージョンの制御はできますが、今回はFirebase拡張がAPIを叩いている為、こちらから変更はできません。

また、Webhookのバージョンは、仕様上はダッシュボードから作り直すことで変えることができるようになっているのですが、選択肢が最新版とそのプレビュー版しかなく、実質的には変更不可となっています。

解決策：API経由でAPIバージョンを指定してWebhookを作成する

先に述べた通り、Stripe アカウント全体の API バージョンを変えられなくても、Webhook だけは特定のバージョンで処理させることが可能です。

参考：公式ドキュメント - Webhook エンドポイント作成
https://docs.stripe.com/api/webhook_endpoints/create#create_webhook_endpoint-api_version

解決方法：Webhook を API(ダッシュボードではない) から明示的に API バージョン指定で再作成
以下のスクリプトを使って、Webhook を 拡張と互換性のあるバージョン（例：2024-06-20） に指定して作り直します。

ts

// createStripeWebhookWithApiVersion.ts
const stripe = require('stripe')('sk_live_...');
const END_POINT = 'https://asia-northeast1-xxxxx.cloudfunctions.net/ext-firestore-stripe-payments-handleWebhookEvents';

const execute = async () => {
try {
const webhookEndpoint = await stripe.webhookEndpoints.create({
url: END_POINT,
api_version: "2024-06-20",
enabled_events: [
"invoice.payment_succeeded",
"invoice.paid",
"checkout.session.completed",
"customer.subscription.created",
"customer.subscription.updated"
]
});
console.log(webhookEndpoint);
} catch (e) {
console.error(e);
}
};

execute();
このスクリプトの実行後、Webhook が正常に受信され、Firestore にも invoice 情報が作成されるようになりました。

なぜこうなったか？

Stripe ではアカウント作成時や更新時に、自動で API バージョンが割り当てられる

Firebase の Stripe 拡張は、特定の API バージョンに依存している

Webhook イベントが異なる形式で送られた場合、関数がパースできずにエラーになる

API バージョンを固定することで、イベント構造が期待どおりになり、正常に処理される

まとめ

Firebase Stripe 拡張を使う際は Stripe の API バージョンに注意

Webhook だけでもバージョンを指定すれば問題を回避できる

テスト環境と本番環境の 微妙な差分がトラブルの原因になる

おわりに

この記事はほとんどChatGPTに書いてもらいました。
ChatGPTに聞きながら格闘していたので、ほとんどの状況は把握されてますので、マーク段形式で出力してもらっのがこれです。追記、修正等、20分ほどで書きあがりました。

本記事の内容が、同じような問題に直面している方の助けになれば嬉しいです。

🙏 ご覧いただきありがとうございました！

Discussion