Webhook - Waffo Pancake

概要

Webhook は、注文、決済、サブスクリプション、返金などのイベントが発生したとき、サーバーにリアルタイム通知を配信します。

Event occurs → Waffo Pancake → fan-out → Your channel(s)

1 つのストアには複数の Webhook を設定でき、それぞれ異なるチャネルに配信されます。利用可能なチャネルは次のとおりです：

チャネル	配信先	ペイロードフォーマット
`http`	あなたの HTTPS エンドポイント	RSA-SHA256 署名付き JSON エンベロープ
`feishu`	Lark / Feishu Bot 受信 Webhook	インタラクティブカード（Lark フォーマット）
`discord`	Discord チャンネル Webhook	Embed メッセージ（Discord フォーマット）
`telegram`	Telegram Bot `sendMessage` URL	HTML 形式のテキスト
`slack`	Slack 受信 Webhook	mrkdwn フィールド付き Attachment

http チャネルは本ページで説明する JSON エンベロープと署名検証を使用します — 本ガイドの大部分はこのチャネルが対象です。IM チャネルでは各プラットフォーム固有のフォーマットが使われ、認証は URL のトークンによって行われます。署名の検証は不要です。

TypeScript をお使いですか？ @waffo/pancake-ts SDK には公開鍵が組み込まれており、環境を自動検出します — 1 行で http チャネルの検証が完了します。

セットアップ

チャネルを選択し URL を準備

HTTP — POST リクエストを受け付け 200 を返すサーバーエンドポイントを構築します。
Feishu / Discord / Telegram / Slack — 対象プラットフォームで Bot または受信 Webhook を作成し、その URL をコピーします。Telegram の場合はメッセージを受信する chat ID も控えておきます。

（HTTP のみ）検証用公開鍵をコピー

Waffo は環境ごと（Test / Production）に 1 組の固定鍵ペアを使用しており、すべてのストアで共通です。Webhook 登録時に公開鍵が返されるわけではなく、ダッシュボードから自分でコピーする方式です。ダッシュボードを開き、任意のストア → 設定 → Webhooks に移動して、連携する環境（Test または Production）の Webhook Public Key をコピーし、サーバーの設定に保存してください。以降すべての HTTP webhook はこの鍵で検証します。

どのストアのダッシュボードでも Test 公開鍵は同じ、Production 公開鍵も同じです —— プラットフォーム共通の鍵です。Webhook URL を追加・編集・削除しても変わりません。

Webhook を登録

ダッシュボード → 設定 → Webhooks から追加するか、POST /v1/actions/store/add-webhook を呼び出します。各 Webhook レコードは 1 つのチャネル、1 つの URL、購読イベント、対象環境（Test の場合は testMode: true、Production の場合は false）を指定します。1 つのストアに複数の Webhook を登録できます。

テストイベントを送信

ダッシュボードの「テストイベントを送信」ボタンを使用して、登録した 1 つまたはすべての Webhook にサンプルイベントを配信します。

署名を検証してイベントを処理

HTTP チャネルでは、以下のコード例を使ってイベント処理前に署名を検証します。IM チャネルは事前レンダリングされたメッセージを配信するため、サーバー側の処理は不要です。

環境の隔離

各 Webhook は testMode フラグによって 1 つの環境に登録されます。Test と Production は完全に独立しています：

項目	Test	Production
Webhook レコード	`testMode: true`	`testMode: false`
署名鍵（HTTP のみ）	Test 鍵ペア	Production 鍵ペア
検証用公開鍵（HTTP のみ）	ダッシュボード Test 鍵	ダッシュボード Production 鍵
配信時のセレクタ	ヘッダー `X-Environment: test`	ヘッダー `X-Environment: prod`（または省略）

各 HTTP ペイロードの mode フィールドはソース環境を示します: "test" または "prod"。

常にイベントの mode に一致する公開鍵を使用してください。Test 鍵では Production イベントを検証できず、その逆も同様です。

ペイロードフォーマット

ヘッダー

ヘッダー	説明
`Content-Type`	`application/json`
`X-Waffo-Signature`	署名文字列: `t=<timestamp>,v1=<signature>`
`X-Waffo-Event`	イベントタイプ（例：`order.completed`）

ボディ

{
  "id": "PAY_6eYCunG3IMmIgcQOnaXdoA",
  "timestamp": "2026-03-10T08:30:00.000Z",
  "eventType": "order.completed",
  "eventId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "completed",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "productName": "Pro Plan",
    "orderMetadata": { "planId": "pro" },
    "orderMerchantExternalId": "ORDER-2026-00891",
    "productMetadata": {},
    "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
    "paymentStatus": "succeeded",
    "paymentMethod": "card",
    "paymentLast4": "4242",
    "paymentDate": "2026-03-10"
  }
}

トップレベルフィールド

フィールド	型	説明
`id`	string	イベントエンティティ ID — ほとんどのイベントで `eventId` と同じ
`timestamp`	string	イベント時刻（ISO 8601 UTC）
`eventType`	string	イベントタイプ（イベントタイプを参照）
`eventId`	string	ビジネスイベント識別子 — イベントタイプごとに異なるエンティティにマッピング（eventId マッピングを参照）
`storeId`	string	Store ID
`storeName`	string	ストア名
`mode`	string	`"test"` または `"prod"`

`data` フィールド

下表は各 data フィールドの型、出現条件、意味を定義します。特定のイベントの正確なフィールド構成は、下記「イベント詳細」にある各イベントの完全な body を参照してください。条件列の「決済イベント」は order.completed と subscription.payment_succeeded、「サブスクリプションイベント」はすべての subscription.* イベントを指します。

フィールド	型	条件	説明
`orderId`	string	常に	注文 ID
`orderStatus`	string	常に	単発注文は `completed`；サブスクリプションは `active` / `canceling` / `canceled` / `past_due`
`buyerEmail`	string	常に	customer のメールアドレス
`currency`	string	常に	ISO 4217 通貨コード（例：`"USD"`、`"JPY"`）
`orderMetadata`	object	常に	チェックアウトセッションからの注文レベルメタデータ（マーチャント定義のキーバリューペア）
`productMetadata`	object	常に	商品の作成/更新時に設定された商品レベルメタデータ
`merchantProvidedBuyerIdentity`	string	チェックアウト時に設定	マーチャントのカスタム customer 識別子
`orderMerchantExternalId`	string	チェックアウト時に設定	注文のマーチャントビジネス側識別子（最大 128 文字）。`refund.*` イベントにも存在し、元の注文から継承されます
`refundTicketMerchantExternalId`	string	`refund.*`、設定時	返金チケットのマーチャントビジネス側識別子（最大 128 文字）
`billingDetail`	object	チェックアウト時に設定	請求先住所（`country`、`isBusiness` など）
`amount`	string	常に	当該イベントの税込み金額（表示フォーマット）。`refund.` では返金額であり、注文金額ではありません*
`taxAmount`	string	常に	税額（表示フォーマット）。`refund.*` では常に `"0"` —— 返金には税の内訳がありません
`taxRate`	number	税率が適用された場合	税率のパーセント値（例：`10` は 10%）
`taxName`	string	税率が適用された場合	税名（例：`"Consumption Tax"`）
`subtotal`	string	利用可能時	税抜き小計（表示フォーマット）。`refund.*` では元の決済を表します
`total`	string	利用可能時	税込み合計（表示フォーマット）。`refund.*` では元の決済を表します
`productName`	string	常に	商品名
`productDescription`	string	商品に設定済み	商品説明
`paymentId`	string	決済と `refund.*` イベント	決済 ID。`refund.*` では返金対象の決済を指します
`paymentStatus`	string	決済と `refund.*` イベント	決済ステータス（`"succeeded"`、`"failed"`）
`paymentDate`	string	決済と `refund.*` イベント	決済日（ISO 8601 日付、例：`"2026-03-10"`）
`paymentMethod`	string	決済と `refund.*`、判明時	決済方法（例：`"card"`）
`paymentLast4`	string	決済と `refund.*`、判明時	決済手段の末尾 4 桁
`paymentFailureReason`	string	決済イベント、設定時	決済の失敗理由
`billingPeriod`	string	サブスクリプションイベント	`"weekly"`、`"monthly"`、`"quarterly"`、`"yearly"`
`currentPeriodStart`	string	サブスクリプションイベント	現在の請求期間の開始日（ISO 8601 日付）
`currentPeriodEnd`	string	サブスクリプションイベント	現在の請求期間の終了日（ISO 8601 日付）
`canceledAt`	string	`subscription.canceling` / `canceled`	キャンセルがリクエストされた時刻（ISO 8601）—— アクセス終了時刻ではありません
`refundStatus`	string	`refund.*`	`"succeeded"` または `"failed"`
`refundReason`	string	`refund.*`、設定時	返金理由
`refundCreatedAt`	string	`refund.*`	返金作成タイムスタンプ（ISO 8601）

金額は表示フォーマット文字列であり、最小通貨単位からすでに変換されています。例えば、USD "29.00" = 2900 セント、JPY "4500" = 4500 円です。利用可能な場合は subtotal と total を使用して明細表示できます。

Webhook ペイロードの taxRate はパーセント値です —— 10 は 10% を意味します。この単位の表記は API 全体で統一を進めており、他の箇所（preview-tax のレスポンス例、TypeScript SDK の型定義）では現在も小数値として記述されています。税の徴収は未開始のため、現時点ではすべての注文で taxRate は 0 です。単位を決め打ちせず、ペイロードの値を読み取ってください。

eventId マッピング

eventId はイベントをトリガーしたビジネスエンティティを識別します。

イベントタイプ	eventId のマッピング先	例
`order.completed`	Payment ID	`PAY_6eYCunG3IMmIgcQOnaXdoA`
`subscription.activated`	Order ID	`ORD_5dXBtmF2HLlHfbPNm0Wcnz`
`subscription.payment_succeeded`	Payment ID	`PAY_6eYCunG3IMmIgcQOnaXdoA`
`subscription.canceling`	Order ID	`ORD_5dXBtmF2HLlHfbPNm0Wcnz`
`subscription.uncanceled`	Order ID	`ORD_5dXBtmF2HLlHfbPNm0Wcnz`
`subscription.updated`	Order ID	`ORD_5dXBtmF2HLlHfbPNm0Wcnz`
`subscription.canceled`	Order ID	`ORD_5dXBtmF2HLlHfbPNm0Wcnz`
`subscription.past_due`	Order ID + 月	`ORD_5dXBtmF2HLlHfbPNm0Wcnz-2026-04`
`refund.succeeded`	Refund ID	`REF_4cWAtlE1GKkGebONl9Xbnx`
`refund.failed`	Refund ID	`REF_4cWAtlE1GKkGebONl9Xbnx`

subscription.past_due は eventId に -YYYY-MM を付加します。同一サブスクリプションにつき、カレンダー月ごとに最大 1 回の past_due イベントがトリガーされます。翌月もまだ滞納中の場合、新しいイベントが発行されます。

イベントタイプ

一覧

イベント	トリガー	eventId
`order.completed`	単発注文の決済が成功	Payment ID
`subscription.activated`	サブスクリプションの初回決済が成功	Order ID
`subscription.payment_succeeded`	サブスクリプション課金の成功 — 初回決済と更新の両方	Payment ID
`subscription.canceling`	キャンセルがリクエストされた — 期間終了まで有効	Order ID
`subscription.uncanceled`	キャンセルが取り消された	Order ID
`subscription.updated`	商品が変更された（アップグレード/ダウングレード）	Order ID
`subscription.canceled`	サブスクリプションが終了（期間終了）	Order ID
`subscription.past_due`	更新決済が失敗	Order ID + 月
`refund.succeeded`	返金が完了	Refund ID
`refund.failed`	返金が失敗	Refund ID

subscription.updated のイベントテンプレートは準備済みで、サブスクリプション商品変更機能のリリース後に有効化されます。

各イベントが注文・サブスクリプション・返金のライフサイクルのどこに位置するか、どの遷移が何も発行しないかはライフサイクルとトリガータイミングを参照してください。

イベント詳細

order.completed

トリガー: 単発注文の決済が初めて成功した時。Body:

{
  "id": "PAY_6eYCunG3IMmIgcQOnaXdoA",
  "timestamp": "2026-03-10T08:30:00.000Z",
  "eventType": "order.completed",
  "eventId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "completed",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "productName": "Pro Plan",
    "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
    "paymentStatus": "succeeded",
    "paymentDate": "2026-03-10",
    "paymentMethod": "card",
    "paymentLast4": "4242"
  }
}

このイベントでは amount は total と同値です。サブスクリプションおよび返金フィールドは含まれません。値がない場合に省略されるフィールド: productDescription、merchantProvidedBuyerIdentity、billingDetail、orderMerchantExternalId、taxRate、taxName、subtotal、total、paymentMethod、paymentLast4。推奨アクション:

デジタル商品の配信（ライセンスキー、ダウンロードリンク、アクティベーションコード）
注文管理システムの更新
customer への確認送信（Waffo の組み込みメールを使用しない場合）

同一注文で order.completed がトリガーされるのは 1 回のみです。返金は refund.succeeded / refund.failed で通知されます。

subscription.activated

トリガー: 新規サブスクリプションの初回決済が成功した時（pending → active）。Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-03-10T08:30:00.000Z",
  "eventType": "subscription.activated",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "active",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "productName": "Pro Plan",
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-03-10",
    "currentPeriodEnd": "2026-04-10"
  }
}

amount はサブスクリプションの通常期価格であり、実際の課金額ではありません。トライアルや初回割引がある場合、初回の課金額は異なります — 実際に回収された金額は subscription.payment_succeeded を使用してください。

このイベントは個別の課金ではなく注文に紐づくため、paymentId を含む決済フィールドは一切含まれません。値がない場合に省略されるフィールド: productDescription、merchantProvidedBuyerIdentity、billingDetail、orderMerchantExternalId、taxRate、taxName、subtotal、total、currentPeriodStart、currentPeriodEnd。推奨アクション:

加入者のアカウントをプロビジョニングしてアクセスを付与
サブスクリプション開始日を記録

サブスクリプションが初めて pending から active に遷移した時にのみ発行されます。同じ初回決済は課金自体に対して subscription.payment_succeeded も発行します — サブスクリプションライフサイクルを参照してください。

subscription.payment_succeeded

トリガー: サブスクリプション課金の成功 — 初回決済、各更新、滞納期間を解消する課金を含みます。Body:

{
  "id": "PAY_7fZDvoH4JNnJhdRPobYepB",
  "timestamp": "2026-04-10T08:30:00.000Z",
  "eventType": "subscription.payment_succeeded",
  "eventId": "PAY_7fZDvoH4JNnJhdRPobYepB",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "active",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "productName": "Pro Plan",
    "paymentId": "PAY_7fZDvoH4JNnJhdRPobYepB",
    "paymentStatus": "succeeded",
    "paymentDate": "2026-04-10",
    "paymentMethod": "card",
    "paymentLast4": "4242",
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-04-10",
    "currentPeriodEnd": "2026-05-10"
  }
}

他の subscription.* イベントと異なり、このイベントは課金に紐づくため決済フィールドを含みます。amount は今期の実際の課金額で、total と同値です。サブスクリプションがキャンセル予定であっても、このイベントに canceledAt は現れません。値がない場合に省略されるフィールド: productDescription、merchantProvidedBuyerIdentity、billingDetail、orderMerchantExternalId、taxRate、taxName、subtotal、total、paymentMethod、paymentLast4、currentPeriodStart、currentPeriodEnd。推奨アクション:

サービス期間の延長
この請求サイクルの請求書を生成
サブスクリプションが以前 past_due だった場合、フルアクセスを復元

subscription.canceling

トリガー: customer またはマーチャントがキャンセルをリクエスト。サブスクリプションは現在の支払い済み期間の終了まで有効です。Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-03-25T11:02:00.000Z",
  "eventType": "subscription.canceling",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "canceling",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "productName": "Pro Plan",
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-03-10",
    "currentPeriodEnd": "2026-04-10",
    "canceledAt": "2026-03-25T11:02:00.000Z"
  }
}

canceledAt はキャンセルがリクエストされた時刻であり、アクセスが終了する時刻ではありません。customer は currentPeriodEnd まで支払い済みです — canceledAt でアクセスを取り消すと、支払い済みのサービスを打ち切ることになります。

このイベントに決済フィールドは含まれません。amount はサブスクリプションの期間あたりの価格であり、個別の課金額ではありません。値がない場合に省略されるフィールド: productDescription、merchantProvidedBuyerIdentity、billingDetail、orderMerchantExternalId、taxRate、taxName、subtotal、total、currentPeriodStart、currentPeriodEnd。推奨アクション:

「サブスクリプションは [日付] に終了します」通知を表示
リテンションフロー（例：割引更新）を提供
アクセスを取り消さないでください — customer は現在の期間分を支払い済みです

customer は期間終了前にキャンセルを取り消すことができます（subscription.uncanceled がトリガーされます）。

subscription.uncanceled

トリガー: 現在の期間が終了する前にキャンセルが取り消された時。Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-03-28T14:20:00.000Z",
  "eventType": "subscription.uncanceled",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "active",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "productName": "Pro Plan",
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-03-10",
    "currentPeriodEnd": "2026-04-10"
  }
}

このイベントに決済フィールドは含まれません。キャンセルが取り消されると canceledAt はクリアされるため、現れません。値がない場合に省略されるフィールド: productDescription、merchantProvidedBuyerIdentity、billingDetail、orderMerchantExternalId、taxRate、taxName、subtotal、total、currentPeriodStart、currentPeriodEnd。推奨アクション:

「まもなく終了」通知を削除
自動更新ステータスを復元

subscription.updated

トリガー: サブスクリプション商品が変更された時（アップグレードまたはダウングレード）。Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-04-02T10:05:00.000Z",
  "eventType": "subscription.updated",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "active",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "49.00",
    "taxAmount": "4.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "44.10",
    "total": "49.00",
    "productName": "Business Plan",
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-04-02",
    "currentPeriodEnd": "2026-05-02"
  }
}

すべてのフィールドは変更後の状態を表します — ペイロードに変更前後の対比は含まれないため、変更前のプランを知ることはできません。アップグレードとダウングレードを区別する必要がある場合は、変更前のプランを自身で記録してください。このイベントに決済フィールドは含まれません。値がない場合に省略されるフィールド: productDescription、merchantProvidedBuyerIdentity、billingDetail、orderMerchantExternalId、taxRate、taxName、subtotal、total、currentPeriodStart、currentPeriodEnd。推奨アクション:

customer のアクセスレベルを更新（機能の追加/削除）
請求記録を更新

subscription.canceled

トリガー: サブスクリプションが終了 — 支払い済み期間が終了し、これ以上の更新は行われません。Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-04-10T00:05:00.000Z",
  "eventType": "subscription.canceled",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "canceled",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "productName": "Pro Plan",
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-03-10",
    "currentPeriodEnd": "2026-04-10",
    "canceledAt": "2026-03-25T11:02:00.000Z"
  }
}

このイベントに決済フィールドは含まれません。canceledAt はキャンセルがリクエストされた時刻で、本イベントより前になります — サブスクリプションはそれ以降も currentPeriodEnd まで有効でした。amount は期間あたりの価格であり、最後の課金額ではありません。値がない場合に省略されるフィールド: productDescription、merchantProvidedBuyerIdentity、billingDetail、orderMerchantExternalId、taxRate、taxName、subtotal、total、currentPeriodStart、currentPeriodEnd、canceledAt。推奨アクション:

アクセスを取り消す（または無料プランにダウングレード）
猶予期間中データを保持（customer が再登録する場合に備えて）
「サブスクリプション終了」確認を送信

これは終了状態です。サブスクリプションは不可逆的に終了しています。

subscription.past_due

トリガー: 更新決済が失敗し、サブスクリプションが滞納状態に入った時。Body:

{
  "id": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
  "timestamp": "2026-05-10T08:31:00.000Z",
  "eventType": "subscription.past_due",
  "eventId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz-2026-05",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "past_due",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "29.00",
    "taxAmount": "2.90",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "productName": "Pro Plan",
    "billingPeriod": "monthly",
    "currentPeriodStart": "2026-04-10",
    "currentPeriodEnd": "2026-05-10"
  }
}

eventId には -YYYY-MM サフィックスが付きます — eventId が id と異なるのはこのイベントだけで、月次の重複排除はこれによって実現されています。決済フィールドを含まないため、課金が失敗した理由はペイロードからは分かりません。amount は請求金額です。値がない場合に省略されるフィールド: productDescription、merchantProvidedBuyerIdentity、billingDetail、orderMerchantExternalId、taxRate、taxName、subtotal、total、currentPeriodStart、currentPeriodEnd。推奨アクション:

customer に支払い方法の更新を通知
オプションでサービスを制限（完全に取り消すのではなく機能を制限）
すぐにアクセスを取り消さないでください — PSP が自動的に課金をリトライする場合があります

重複排除: サブスクリプションごとにカレンダー月あたり最大 1 回の past_due イベント。翌月もまだ滞納中の場合、新しいイベントが発行されます。

refund.succeeded

トリガー: 返金が完了し、資金が返還された時。Body（部分返金の例: 元の決済 29.00 に対して 10.00 の返金）:

{
  "id": "REF_4cWAtlE1GKkGebONl9Xbnx",
  "timestamp": "2026-03-12T09:15:23.481Z",
  "eventType": "refund.succeeded",
  "eventId": "REF_4cWAtlE1GKkGebONl9Xbnx",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "completed",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "refundTicketMerchantExternalId": "REF-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "10.00",
    "taxAmount": "0.00",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "productName": "Pro Plan",
    "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
    "paymentStatus": "succeeded",
    "paymentDate": "2026-03-10",
    "paymentMethod": "card",
    "paymentLast4": "4242",
    "refundStatus": "succeeded",
    "refundReason": "Customer requested refund",
    "refundCreatedAt": "2026-03-12T09:15:00.000Z"
  }
}

amount は今回の返金額、total は元の決済金額です。部分返金では両者が一致しません — 計上には必ず amount を使用し、total は使用しないでください。

subtotal / total / taxRate / taxName は元の決済基準で、比較用に保持されています。返金には税の内訳がないため taxAmount は常に "0" です。税の詳細は元の注文を確認してください。paymentId は返金対象の課金を指します — サブスクリプションの場合は特定の期の課金であり、どの期が返金されたかはこれで判断できます。ペイロードにはその決済の累計返金額は含まれないため、1 つの決済が複数回返金される可能性がある場合は自身で記録してください。値がない場合に省略されるフィールド: productDescription、merchantProvidedBuyerIdentity、billingDetail、orderMerchantExternalId、refundTicketMerchantExternalId、taxRate、taxName、subtotal、total、paymentMethod、paymentLast4、refundReason。推奨アクション:

配信済みデジタル商品を取り消す（ライセンスの失効、ダウンロードの無効化）
注文ステータスを「返金済み」に更新

refund.failed

トリガー: 返金処理が失敗した時。Body:

{
  "id": "REF_4cWAtlE1GKkGebONl9Xbnx",
  "timestamp": "2026-03-12T09:15:23.481Z",
  "eventType": "refund.failed",
  "eventId": "REF_4cWAtlE1GKkGebONl9Xbnx",
  "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx",
  "storeName": "My Store",
  "mode": "prod",
  "data": {
    "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz",
    "orderStatus": "completed",
    "buyerEmail": "customer@example.com",
    "currency": "USD",
    "orderMetadata": { "planId": "pro" },
    "productMetadata": {},
    "orderMerchantExternalId": "ORDER-2026-00891",
    "refundTicketMerchantExternalId": "REF-2026-00891",
    "billingDetail": { "country": "JP", "isBusiness": false },
    "amount": "10.00",
    "taxAmount": "0.00",
    "taxRate": 10,
    "taxName": "Consumption Tax",
    "subtotal": "26.10",
    "total": "29.00",
    "productName": "Pro Plan",
    "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
    "paymentStatus": "succeeded",
    "paymentDate": "2026-03-10",
    "paymentMethod": "card",
    "paymentLast4": "4242",
    "refundStatus": "failed",
    "refundReason": "Customer requested refund",
    "refundCreatedAt": "2026-03-12T09:15:00.000Z"
  }
}

資金は移動していません。amount は試行された返金額です — 返金として計上しないでください。

その他の構造は refund.succeeded と同じです。2 つのイベントを区別できるのは refundStatus のみなので、フィールドの有無ではなくこれで分岐してください。ペイロードに失敗理由は含まれないため、ダッシュボードで返金チケットを確認してください。値がない場合に省略されるフィールド: refund.succeeded と同じ。推奨アクション:

手動確認のために障害をログに記録
商品を取り消さないでください（返金は完了していません）

ライフサイクルとトリガータイミング

イベントは購入者のクリック時ではなく、背後のビジネス事実が確定した時点で発行されます。決済系イベントは決済プロバイダーが課金を確認した後、サブスクリプション状態系イベントはプロバイダーが状態変更を確認した後に発行されます。発行後、エンドポイントへの配信は通常数秒以内に完了します。 timestamp フィールドはイベントが生成された時刻を保持します。リトライでも同じ値が使われ、配信試行ごとに変化することはありません。

配信タイムライン

決済が確定した地点は、チェックアウトのリダイレクトではなくイベントです。購入者がリダイレクト前にブラウザを閉じても、イベントは届きます。

一回限りの注文のライフサイクル

タイミング	イベント
決済の確定	`order.completed`
決済の拒否 — 注文は支払い可能なまま	なし
チェックアウトの期限切れまたは購入者によるキャンセル	なし
その決済に対する返金の確定	`refund.succeeded` / `refund.failed`

決済が拒否された注文は pending のまま残り、購入者は同じ注文で再度支払えます。order.completed は注文につき 1 回だけ — 最終的に成功した決済が発行します。

サブスクリプションライフサイクル

タイミング	イベント
初回決済の確定	`subscription.activated` と `subscription.payment_succeeded`
更新決済の確定	`subscription.payment_succeeded`
滞納中サブスクリプションの支払い成功	`subscription.payment_succeeded`
`active` 状態で更新決済が拒否	`subscription.past_due`
`past_due` 状態で更新決済が再度拒否	`subscription.canceled` — サブスクリプションは終了
キャンセルのリクエスト	`subscription.canceling`、即時
キャンセルの取り消し	`subscription.uncanceled`、即時
終了の確認	`subscription.canceled`、`currentPeriodEnd` の前後
初回決済前のキャンセルまたはタイムアウト	なし
課金期間の繰り越し	なし

初回決済は2 つのイベントを発行します。subscription.activated（注文に紐づく）と subscription.payment_succeeded（課金に紐づく）です。両者は独立して配信されるため、順序も間隔も保証されません。activated でアクセスをプロビジョニングし、payment_succeeded で受領を記録してください — 両方を「新規加入者」として扱うと、オンボーディングが 2 回実行されます。

キャンセルは 2 つの時点に分かれます。subscription.canceling はキャンセルがリクエストされた瞬間に発行され、終了自体は支払い済み期間の終わりに予約されます。subscription.canceled は決済プロバイダーが終了を確認した後 — リクエスト時点ではなく currentPeriodEnd の前後 — に発行されます。その間もサブスクリプションは有効で、customer はキャンセルを取り消せます。滞納中のサブスクリプションは次の更新失敗で終了します。1 回目の拒否で active から past_due に移って subscription.past_due を発行し、past_due 状態でさらに拒否されるとサブスクリプションが終了して subscription.canceled を発行します。

終了状態	意味	イベント
`canceled`	アクティブ化後の終了、または初回決済前のキャンセル	`subscription.canceled` — アクティブだった場合のみ
`closed`	決済期限内に初回決済が完了しなかった	なし
`expired`	定期サブスクリプションが期限に到達	なし

返金のライフサイクル

返金イベントは最後のステップ — 決済プロバイダーが結果を確定した時点 — でのみ発行されます。返金チケットの作成・承認・却下・再提出では webhook は発生しないため、審査中のチケットは確定するまでエンドポイントからは見えません。API 経由の返金は自動承認され、そのまま processing に入ります。チケットの状態と照会方法は返金エンドポイントを参照してください。

イベントが発行されないケース

ケース	理由
一回限りの決済が拒否	注文は `pending` のままで支払い可能 — 確定した事実がない
チェックアウトの期限切れまたは購入者によるキャンセル	注文は一度も支払われずに `canceled` で終わる
初回決済前にキャンセルまたはタイムアウトしたサブスクリプション	アクティブ化されていないため、`canceled` / `closed` は通知を伴わない
定期サブスクリプションが期限に到達	終了日は購入時点で確定している
課金期間の繰り越し	更新決済が新しい期間を報告済み
返金チケットの作成・承認・却下・再提出	確定した結果のみを報告

署名検証

本番環境では必ず署名を検証してください。 検証なしでは、誰でもエンドポイントに偽造リクエストを送信できます。

アルゴリズム

Parse t (timestamp in ms) and v1 (Base64 signature) from X-Waffo-Signature header
Build signature input: `${t}.${rawRequestBody}`
Verify v1 using RSA-SHA256 with the Waffo public key
(Recommended) Check that t is within 5 minutes of current time to prevent replay attacks

SDK の使用（推奨）

SDK は公開鍵を埋め込み、環境を自動検出し、フォーマットの正規化を処理します。

import { verifyWebhook, WebhookEventType } from "@waffo/pancake-ts";

app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = verifyWebhook(
      req.body.toString("utf-8"),
      req.headers["x-waffo-signature"] as string,
    );

    res.status(200).send("OK");

    switch (event.eventType) {
      case WebhookEventType.OrderCompleted:
        // Deliver digital goods
        break;
      case WebhookEventType.SubscriptionActivated:
        // Provision subscription access
        break;
      case WebhookEventType.SubscriptionCanceled:
        // Revoke access
        break;
    }
  } catch {
    res.status(401).send("Invalid signature");
  }
});

SDK Webhook ドキュメントの詳細をご覧ください。

手動検証

TypeScript SDK を使用しない場合は、署名検証を手動で実装してください。

const crypto = require('crypto');

// From Dashboard → API と開発 → Webhook Public Key (PEM format)
const WAFFO_WEBHOOK_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----`;

function parseSignatureHeader(header) {
  const parts = {};
  for (const pair of header.split(',')) {
    const [key, ...rest] = pair.split('=');
    parts[key.trim()] = rest.join('=').trim();
  }
  return parts;
}

function verifyWebhookSignature(rawBody, signatureHeader, publicKey) {
  const { t, v1 } = parseSignatureHeader(signatureHeader);
  if (!t || !v1) return false;

  // Replay protection: 5-minute tolerance
  const tolerance = 5 * 60 * 1000;
  if (Math.abs(Date.now() - Number(t)) > tolerance) return false;

  // Verify RSA-SHA256 signature
  const signatureInput = `${t}.${rawBody}`;
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(signatureInput);
  return verifier.verify(publicKey, v1, 'base64');
}

app.post('/webhooks',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['x-waffo-signature'];
    const rawBody = req.body.toString('utf-8');

    if (!sig || !verifyWebhookSignature(rawBody, sig, WAFFO_WEBHOOK_PUBLIC_KEY)) {
      return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(rawBody);
    res.status(200).send('OK');

    // Process asynchronously
    handleEvent(event).catch(console.error);
  }
);

async function handleEvent(event) {
  switch (event.eventType) {
    case 'order.completed':
      await grantAccess(event.data.buyerEmail, event.data.productName);
      break;
    case 'subscription.activated':
      await createSubscription(event.data.buyerEmail, event.data.orderId);
      break;
    case 'subscription.payment_succeeded':
      await extendSubscription(event.data.orderId);
      break;
    case 'subscription.canceling':
      await markCanceling(event.data.orderId);
      break;
    case 'subscription.canceled':
      await revokeAccess(event.data.orderId);
      break;
    case 'subscription.past_due':
      await notifyPastDue(event.data.buyerEmail, event.data.orderId);
      break;
    case 'refund.succeeded':
      await revokeAccess(event.data.orderId);
      break;
    case 'refund.failed':
      await flagForReview(event.data.orderId);
      break;
  }
}

import json, time
from base64 import b64decode
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
from flask import Flask, request

app = Flask(__name__)

WAFFO_WEBHOOK_PUBLIC_KEY = """-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----"""

def verify_webhook_signature(raw_body, signature_header, public_key_pem):
    parts = dict(p.split("=", 1) for p in signature_header.split(",") if "=" in p)
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1:
        return False

    # Replay protection: 5-minute tolerance
    if abs(int(time.time() * 1000) - int(t)) > 5 * 60 * 1000:
        return False

    signature_input = f"{t}.{raw_body}".encode("utf-8")
    public_key = serialization.load_pem_public_key(public_key_pem.encode("utf-8"))
    try:
        public_key.verify(b64decode(v1), signature_input, padding.PKCS1v15(), hashes.SHA256())
        return True
    except Exception:
        return False

@app.route("/webhooks", methods=["POST"])
def handle_webhook():
    sig = request.headers.get("X-Waffo-Signature", "")
    raw_body = request.get_data(as_text=True)

    if not verify_webhook_signature(raw_body, sig, WAFFO_WEBHOOK_PUBLIC_KEY):
        return "Invalid signature", 401

    event = json.loads(raw_body)
    # Process event...
    return "OK", 200

package main

import (
	"crypto"
	"crypto/rsa"
	"crypto/sha256"
	"crypto/x509"
	"encoding/base64"
	"encoding/pem"
	"fmt"
	"io"
	"math"
	"net/http"
	"strconv"
	"strings"
	"time"
)

const waffoPublicKeyPEM = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----`

func verifyWebhookSignature(rawBody []byte, signatureHeader string) bool {
	var t, v1 string
	for _, pair := range strings.Split(signatureHeader, ",") {
		parts := strings.SplitN(pair, "=", 2)
		if len(parts) != 2 { continue }
		switch strings.TrimSpace(parts[0]) {
		case "t": t = strings.TrimSpace(parts[1])
		case "v1": v1 = strings.TrimSpace(parts[1])
		}
	}
	if t == "" || v1 == "" { return false }

	ts, err := strconv.ParseInt(t, 10, 64)
	if err != nil || math.Abs(float64(time.Now().UnixMilli()-ts)) > 5*60*1000 {
		return false
	}

	block, _ := pem.Decode([]byte(waffoPublicKeyPEM))
	if block == nil { return false }
	pub, err := x509.ParsePKIXPublicKey(block.Bytes)
	if err != nil { return false }
	rsaPub, ok := pub.(*rsa.PublicKey)
	if !ok { return false }

	hash := sha256.Sum256([]byte(fmt.Sprintf("%s.%s", t, string(rawBody))))
	sig, err := base64.StdEncoding.DecodeString(v1)
	if err != nil { return false }
	return rsa.VerifyPKCS1v15(rsaPub, crypto.SHA256, hash[:], sig) == nil
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	rawBody, _ := io.ReadAll(r.Body)
	if !verifyWebhookSignature(rawBody, r.Header.Get("X-Waffo-Signature")) {
		http.Error(w, "Invalid signature", http.StatusUnauthorized)
		return
	}
	w.WriteHeader(http.StatusOK)
	w.Write([]byte("OK"))
}

func main() {
	http.HandleFunc("/webhooks", webhookHandler)
	http.ListenAndServe(":8080", nil)
}

署名検証には生のリクエストボディを使用する必要があります。 フレームワークが自動的に JSON をパースする場合、署名チェックは失敗します。検証前に未変更の生の文字列を取得してください。

レスポンス要件

2xx ステータスコードを返してください（推奨: 200）
10 秒以内に応答してください
レスポンスボディは問いません

// Recommended: respond immediately, process async
app.post('/webhooks', (req, res) => {
  res.status(200).send('OK');
  processEventAsync(req.body);
});

非 2xx レスポンスまたはタイムアウトはリトライをトリガーします。

リトライポリシー

配信失敗時は指数バックオフで自動的にリトライされます。

項目	詳細
リトライ回数	最大 3 回（初回を含めて合計 4 回）
戦略	指数バックオフ
タイムアウト	非 2xx またはタイムアウトウィンドウ内にレスポンスなし
最終失敗	すべてのリトライが尽きた後、配信は `failed` としてマークされます

配信ステータス

ステータス	説明
`pending`	作成済み、配信待ちまたはリトライ中
`success`	配信成功（サーバーが 2xx を返した）
`failed`	すべてのリトライが尽きた

ダッシュボードの Webhook ログで配信履歴を確認できます。ステータス、HTTP レスポンスコード、レスポンスボディ（1000 文字に切り詰め）が含まれます。

重複の処理

ネットワークの問題により、同じイベントが複数回配信される場合があります。イベント処理が冪等であることを確認してください。 重複排除には eventType + eventId の組み合わせ（システム内で一意制約あり）を使用してください。

async function handleEvent(event) {
  const exists = await db.query(
    'SELECT 1 FROM processed_webhooks WHERE event_type = $1 AND event_id = $2',
    [event.eventType, event.eventId]
  );
  if (exists.rows.length > 0) return; // Already processed

  await processEventLogic(event);

  await db.query(
    'INSERT INTO processed_webhooks (event_type, event_id, processed_at) VALUES ($1, $2, NOW())',
    [event.eventType, event.eventId]
  );
}

同一ビジネスイベント（同一の eventType + eventId）は 1 つの配信レコードのみを作成します — 重複することはありません。ただし、リトライにより単一の配信がエンドポイントに複数回到達する場合があります。

ベストプラクティス

必ず署名を検証する

常に X-Waffo-Signature を検証してください。検証なしでは、誰でもエンドポイントに偽造リクエストを送信できます。

HTTPS を使用する

本番環境の Webhook URL は、転送中のデータを保護するために HTTPS を使用する必要があります。

即座にレスポンスし、非同期で処理する

すぐに 200 を返し、ビジネスロジックはバックグラウンドで処理してください。レスポンスが遅いと不要なリトライが発生します。

eventType + eventId で重複排除する

eventType + eventId の組み合わせで重複排除してください。同じ配信が複数回処理されても副作用がないようにしてください。

タイムスタンプを確認する

リプレイ攻撃を防ぐために、t タイムスタンプが現在時刻から 5 分以内であることを確認してください。

正しい環境の鍵を使用する

Test と Production は異なる鍵ペアを使用します。ペイロードの mode フィールドに公開鍵を一致させてください。

受信ペイロードをログに記録する

デバッグのために受信したペイロードを保存してください。ダッシュボードでも配信ログクエリを提供しています。

購読したすべてのイベントを処理する

まだ必要でなくても、購読しているすべてのイベントに分岐を追加してください。未処理のイベントには 200 を返してください — エラーを返すと不要なリトライがトリガーされます。

テスト

テストイベントの送信（推奨）

ダッシュボードの「テストイベントを送信」ボタンを使用して、実際のトランザクションをトリガーせずにテストイベントを送信します。テストイベントは固定のサンプルデータ（amount 0、taxAmount 0、product “[TEST] Webhook Verification”）を使用し、常に Test 鍵で署名されます。 10 種類すべてのイベントタイプがサポートされています — 各イベントをテストしてハンドラーを検証してください。

Test モードを使用する

ダッシュボードで Test 環境の Webhook URL とイベントを設定します
Test モードで実際の操作を行います（注文の作成、決済の処理）
イベントは Test 署名鍵を使用して Test Webhook URL に送信されます

ローカル開発

トンネルを使用してローカルサーバーを公開します。

ngrok http 8080
# Use the generated URL as your Test Webhook URL
# e.g., https://abc123.ngrok.io/webhooks

配信ログ

ダッシュボードで Webhook 配信履歴を確認できます。

ステータス: pending / success / failed
HTTP ステータスコード: サーバーのレスポンスコード
レスポンスボディ: サーバーのレスポンス（1000 文字に切り詰め）
タイムスタンプ: 最終配信試行

FAQ

Webhook が受信できない

ダッシュボードで Webhook URL が設定され、公開アクセス可能であることを確認してください
正しいイベントタイプを購読していることを確認してください
正しい環境（Test / Production）を使用していることを確認してください
ファイアウォールが Waffo からのリクエストを許可していることを確認してください
ダッシュボードの「テストイベントを送信」で問題を切り分けてください

署名検証が失敗する

正しい環境の公開鍵（Test vs Production）を使用していることを確認してください
生のリクエストボディを使用していることを確認してください — パースされた JSON オブジェクトではありません
ミドルウェアやプロキシがリクエストボディを変更していないか確認してください
署名入力の形式が ${t}.${rawBody}（タイムスタンプ + ドット + 生のボディ）であることを確認してください
TypeScript を使用している場合は、@waffo/pancake-ts SDK に切り替えてください — 鍵の選択とフォーマットの正規化を自動的に処理します

重複イベントが受信される

これは通常のリトライ動作です。エンドポイントが非 2xx を返したかタイムアウトした場合、システムがリトライします。ハンドラーが冪等であることを確認してください — 重複排除には eventType + eventId の組み合わせを使用してください。

サブスクリプションの初回決済で 2 つのイベントが届くのはなぜですか？

初回の課金は 2 つの事実を同時に確定させます。サブスクリプションがアクティブになったこと（subscription.activated、注文に紐づく）と、支払いを受領したこと（subscription.payment_succeeded、課金に紐づく）です。両者は独立して配信されるため、順序も間隔も保証されません。activated でアクセスをプロビジョニングし、payment_succeeded で受領を記録すれば、初回決済の処理はちょうど 1 回だけ実行されます。

`subscription.canceled` は正確にはいつ届きますか？

currentPeriodEnd の前後です — キャンセルがリクエストされた時点ではありません。キャンセルのリクエストは即座に subscription.canceling を発行し、終了を支払い済み期間の終わりに予約します。決済プロバイダーが終了を確認した後に subscription.canceled が続きます。アクセスをいつ終了すべきかは、canceling ペイロードの currentPeriodEnd で判断してください。

`subscription.canceling` と `subscription.canceled` の違い

canceling: キャンセルがリクエストされましたが、現在の支払い済み期間がまだ終了していません。サブスクリプションはまだ有効で、customer はキャンセルを取り消すことができます（uncanceled がトリガーされます）。アクセスを取り消さないでください。
canceled: サブスクリプションは終了しています。これは不可逆です — アクセスを取り消すか権限をダウングレードしてください。

各イベントの `data.amount` の意味

すべてのイベント: data.amount はそのイベントに対する取引金額（税込み）です。

order.completed / subscription.activated — 決済金額
subscription.payment_succeeded — 今期の更新金額
subscription.past_due — 今期の請求金額
refund.succeeded / refund.failed — 返金金額
subscription.canceling / subscription.canceled / subscription.uncanceled — サブスクリプションの期間あたりの金額

​概要

​セットアップ

​環境の隔離

​ペイロードフォーマット

​ヘッダー

​ボディ

​トップレベルフィールド

​data フィールド

​eventId マッピング

​イベントタイプ

​一覧

​イベント詳細

​ライフサイクルとトリガータイミング

​配信タイムライン

​一回限りの注文のライフサイクル

​サブスクリプションライフサイクル

​返金のライフサイクル

​イベントが発行されないケース

​署名検証

​アルゴリズム

​SDK の使用（推奨）

​手動検証

​レスポンス要件

​リトライポリシー

​配信ステータス

​重複の処理

​ベストプラクティス

​テスト

​テストイベントの送信（推奨）

​Test モードを使用する

​ローカル開発

​配信ログ

​FAQ

​Webhook が受信できない

​署名検証が失敗する

​重複イベントが受信される

​サブスクリプションの初回決済で 2 つのイベントが届くのはなぜですか？

​subscription.canceled は正確にはいつ届きますか？

​subscription.canceling と subscription.canceled の違い

​各イベントの data.amount の意味

概要

セットアップ

環境の隔離

ペイロードフォーマット

ヘッダー

ボディ

トップレベルフィールド

`data` フィールド

eventId マッピング

イベントタイプ

一覧

イベント詳細

ライフサイクルとトリガータイミング

配信タイムライン

一回限りの注文のライフサイクル

サブスクリプションライフサイクル

返金のライフサイクル

イベントが発行されないケース

署名検証

アルゴリズム

SDK の使用（推奨）

手動検証

レスポンス要件

リトライポリシー

配信ステータス

重複の処理

ベストプラクティス

テスト

テストイベントの送信（推奨）

Test モードを使用する

ローカル開発

配信ログ

FAQ

Webhook が受信できない

署名検証が失敗する

重複イベントが受信される

サブスクリプションの初回決済で 2 つのイベントが届くのはなぜですか？

`subscription.canceled` は正確にはいつ届きますか？

`subscription.canceling` と `subscription.canceled` の違い

各イベントの `data.amount` の意味