メインコンテンツへスキップ

​
Webhookとは？

Webhookは、イベントが発生した時にWaffo Pancakeがサーバーに自動送信する通知です — 支払い成功、サブスクリプション更新、返金処理など。 Webhookが必要な理由：
  • 配信の自動化：支払い後すぐにダウンロードリンクを送信したりアクセスを付与
  • システムの同期：サブスクリプションステータス変更時にデータベースを更新
  • リアルタイム対応：失敗した支払い、キャンセル、返金にリアルタイムで対応

​
ステップ1：DashboardでWebhook URLを設定

1

設定に移動

Dashboardで設定 → Webhooksに移動します。
Webhook設定ページ
2

Webhook URLを設定

Waffo Pancakeがイベント通知を送信する先のURLを入力します。
  • テストモードURL：開発/ステージングサーバー（例：https://staging.yoursite.com/webhooks/waffo）
  • 本番URL：本番サーバー（例：https://yoursite.com/webhooks/waffo）
テストと本番で異なるURLを設定できます。テストイベントと実際のイベントを分離できます。
3

保存

保存をクリックしてWebhook通知を有効化します。

​
ステップ2：イベントタイプを理解

Waffo Pancakeは以下のWebhookイベントを送信します：

​
決済イベント

イベントトリガータイミング一般的なアクション
payment.succeeded支払いが正常に完了商品を配信、アクセスを付与
payment.failed支払い試行が失敗顧客に通知、リトライ
payment.refunded返金が処理されたアクセスを取り消し、記録を更新

​
サブスクリプションイベント

イベントトリガータイミング一般的なアクション
subscription.created新しいサブスクリプション開始アカウント作成、制限設定
subscription.updatedプラン変更または更新アクセスレベルを更新
subscription.canceledサブスクリプションが完全に終了アクセスを取り消し
subscription.expiredサブスクリプションが期限切れリソースをクリーンアップ

​
ステップ3：メール通知を設定

Webhookイベントに加えて、あなたと顧客のメール通知も設定できます。

​
マーチャント通知

設定 → 通知で、どのイベントがメールアラートをトリガーするか選択：
  • 新規注文
  • 新規サブスクリプション
  • 支払い失敗
  • 返金リクエスト
通知設定

​
顧客通知

顧客は以下のイベントで自動的にメールを受信：
  • 注文確認
  • サブスクリプション確認
  • サブスクリプション更新
  • サブスクリプションキャンセル
  • 支払い失敗
通知設定でこれらをオン/オフできます。

​
Webhookの仕組み

イベント発生（例：支払い成功）
    ↓
Waffo PancakeがWebhook URLにPOSTリクエストを送信
    ↓
サーバーがイベントを受信
    ↓
サーバーが処理（商品配信、データベース更新など）
    ↓
サーバーが200 OKを返す

​
リトライポリシー

サーバーが2xxステータスコードで応答しない場合、Waffo Pancakeがリトライ：
リトライ回数遅延
1回目5分
2回目30分
3回目2時間
4回目8時間
5回目24時間
5回のリトライがすべて失敗すると、イベントは失敗としてマークされます。

​
開発者向け：コード統合

Webhookをサーバーに統合する場合のフロー：

​
1. Webhookエンドポイントを作成

サーバーにイベントを受信するPOSTエンドポイントが必要です。具体的な実装は技術スタックによります。

​
2. 署名を検証

すべてのWebhookリクエストにはセキュリティ用の署名ヘッダーが含まれます。リクエストがWaffo Pancakeからのものであることを確認してください。

​
3. イベントを処理

イベントタイプとデータを解析し、適切なアクション（商品配信、サブスクリプションステータス更新など）を実行。

​
4. 迅速に応答

できるだけ早く200ステータスコードを返してください。重い処理が必要な場合は、応答後に非同期で実行。
詳細なコード例と署名検証については、APIリファレンス — Webhooksをご覧ください。

​
Webhookのテスト

1

テストWebhook URLを設定

Dashboard → 設定 → Webhooksで、テストサーバーのURLを入力。
2

テスト購入を行う

テストモードで購入を作成。テストURLにWebhookイベントがトリガーされます。
3

受信を確認

サーバーログを確認して、Webhookが正しく受信・処理されたことを確認。
ローカル開発では、ngrokなどのツールを使ってローカルサーバーをインターネットに公開し、Waffo Pancakeがアクセスできるようにしてください。

​
ベストプラクティス

  1. 迅速に応答：すぐに200を返し、非同期で処理
  2. 重複を処理：イベントは複数回送信される可能性あり — 冪等な処理を実装
  3. 署名を検証：処理前に必ずWebhook署名を検証
  4. すべてを記録：デバッグ用に受信したWebhookのログを保持
  5. 失敗を監視：Dashboardで失敗したWebhook配信を確認

​
チェックリスト

  • テスト・本番のWebhook URLを設定
  • チームのメール通知を設定
  • 顧客の通知設定を構成
  • テストWebhookの受信と処理を確認
  • 署名検証を実装（コード統合の場合）

​
次のステップ

返金を管理

返金リクエストの処理と返金状況の追跡

APIリファレンス — Webhooks

詳細なWebhookペイロード形式とコード例