Stripe Apps の UI 拡張を開発していると、Stripe Dashboard 上の拡張 UI から自前のバックエンド API を呼び出すケースが多々あります。このとき、バックエンド API には、そのリクエストが本当に Stripe Appsからきたものであるかを検証できる仕組みが必要です。

Stripe 公式が提供する fetchStripeSignature を活用することで、署名付きリクエストを簡単に実現でき、セキュリティと信頼性を大きく高めることができます。

fetchStripeSignature 関数とは

fetchStripeSignature は、Stripe Apps の UI 拡張 SDK が提供するユーティリティ関数で、これを使うことで Stripe が発行したリクエスト署名（Stripe-Signature ヘッダー）を取得できます。

この署名を API リクエストのヘッダーに付与し、バックエンド側で検証することで、Stripe Dashboard 上の正規の拡張 UI からのリクエストであることを保証できるのです。

Extension SDK API reference

Build server-side logic

なぜ fetchStripeSignature が必要なのか

バックエンド API の実装を試すだけであれば、この関数がなくても動作させることができます。ですが、外部から悪意のあるリクエストが来る可能性を考えると、リクエストの検証は必ず必要です。Stripe 公式ドキュメントでも「UI 拡張→API 連携時は必ず署名付きリクエスト＋サーバー側検証を」と明記されていますし、 Stripe Apps の審査や運用でも、署名検証は必須レベルの要件となっています。

署名付き fetch の共通化ヘルパー関数

Stripe Apps では、API 呼び出しのたびに fetchStripeSignature で署名取得、fetch で API リクエスト、ヘッダーに署名を付与という処理を作ることになります。これを共通化ヘルパー関数としてまとめることで、安全・簡単・再利用性の高い API 呼び出しが実現できます。

// src/libs/signedFetch.ts
import { fetchStripeSignature } from '@stripe/ui-extension-sdk/utils';

export type SignedFetchOptions = {
  path: string;
  method?: string;
  body?: any;
  headers?: Record<string, string>;
  baseUrl: string;
};

export async function signedFetch({
  path,
  method = 'POST',
  body,
  headers = {},
  baseUrl,
}: SignedFetchOptions) {
  const signature = await fetchStripeSignature();
  
  const fetchHeaders: Record<string, string> = {
    'Content-Type': 'application/json',
    'Stripe-Signature': signature,
    ...headers,
  };

  const res = await fetch(`${baseUrl}${path}`, {
    method,
    headers: fetchHeaders,
    body: body ? JSON.stringify(body) : undefined,
  });

  return res;
}

この関数は次のように利用します。

const res = await signedFetch({
  path: '/prices',
  baseUrl: String(environment.constants.API_BASE),
  method: 'POST',
  // body, headers も必要に応じて追加
});

const data = await res.json();

バックエンド側の実装ポイント

バックエンド側では、Stripe-Signature ヘッダーを必ず検証する必要があります。公式 SDK の stripe.webhooks.signature.verifyHeaderAsync などを活用し、署名不正時は即エラーで弾く実装が重要です。

まとめ

Stripe Apps の UI 拡張とバックエンド API 連携では、fetchStripeSignature による署名付きリクエストとサーバー側検証が必須となります。

この仕組みを共通化ヘルパー関数として実装することで、セキュリティ・保守性・開発効率のすべてを高めることができるのです。Stripe Apps 開発の現場では、このパターンを標準化することをお勧めします。

Tag: ヘルパー関数

Stripe Apps で fetchStripeSignature を活用したセキュアな API 連携と共通化ヘルパー設計