Webhook通知を設定

Webhookとは？

Webhookは、イベントが発生した時にWaffo Pancakeがサーバーに自動送信する通知です — 支払い成功、サブスクリプション更新、返金処理など。 Webhookが必要な理由：

配信の自動化：支払い後すぐにダウンロードリンクを送信したりアクセスを付与
システムの同期：サブスクリプションステータス変更時にデータベースを更新
リアルタイム対応：失敗した支払い、キャンセル、返金にリアルタイムで対応

ステップ1：DashboardでWebhookを追加

設定に移動

Dashboardで 設定 → Webhooks に移動します。

Webhooks設定ページ。Test ModeとLive Modeの2セクションに分かれている

フォーマットを選択

送信先に合わせてペイロードの形式を選びます。自前のバックエンドなら Raw JSON、Slack / Discord / Lark（飛書）/ Telegram などのチャットプラットフォーム形式を選べば、その先でそのまま自然に表示されます。あるいは OpenClaw / Hermes（セルフホストの Pancake プラグイン）を選んで独自ルーティングや下流処理に流すこともできます。詳細は下記のペイロード形式を選ぶを参照。

Webhookを追加モーダルでFormatドロップダウンが開いている状態：Raw / Feishu / Slack / Discord / Telegram / OpenClaw・Hermes

Webhook URLを設定

Waffo Pancakeがイベント通知を送信する先のURLを入力します。

テストモードURL：開発/ステージングサーバー（例：https://staging.yoursite.com/webhooks/waffo）
本番URL：本番サーバー（例：https://yoursite.com/webhooks/waffo）

テストと本番で異なるURLを設定できます。テストイベントと実際のイベントを分離できます。

前のステップで Telegram を選んだ場合は、URLではなく Bot Token と Chat ID を入力します。取得方法は下記の Telegram を参照してください。

イベントを選択

すべてのイベントがデフォルトで購読されています。不要なイベントのチェックを外してください。

保存

Save Webhook をクリックします。

1つの環境につき 最大10個のWebhook を設定できるので、同じイベントを複数の宛先（自前のバックエンド、Slackチャンネル、社内ダッシュボードなど）にファンアウトしたい場合も、自前のリレーを書く必要はありません。同じ環境で同じURLを2回登録することはできません。

本番運用の注意：本番モード（Live Mode）のWebhookは、ストアの審査通過後にのみ配信されます。審査中はテストモードのWebhookをステージング側で利用してください。

ペイロード形式を選ぶ

Waffoは送信先が期待するフォーマットでイベントを配信できるので、自分で変換器を書く必要はありません。Webhook追加時にフォーマットを選ぶだけで、後から変えたければ別フォーマットで追加し直せばOKです。

フォーマット	使う場面	Endpoint
Raw（既定）	自前のバックエンドを叩き、署名付きの正規JSONペイロードが欲しいとき。	任意のHTTPS URL
飛書 / Lark	カスタムボット経由でLark（飛書）のグループに投稿したいとき。	`https://open.feishu.cn/open-apis/bot/v2/hook/<hook-id>`
Slack	Incoming Webhook経由でSlackチャンネルに投稿したいとき。	`https://hooks.slack.com/services/T.../B.../<token>`
Discord	チャンネルWebhook経由でDiscordチャンネルに投稿したいとき。	`https://discord.com/api/webhooks/<id>/<token>`
Telegram	ボット経由でTelegramのチャットやグループに投稿したいとき。	Bot Token + Chat ID（URLはWaffoが組み立て）
OpenClaw / Hermes	セルフホストの Pancakeプラグインを経由してカスタム下流処理にルーティングしたいとき。	`https://relay.waffo.ai/webhook/<webhook-id>`

RSA-SHA256署名が付くのは Raw だけです。チャットプラットフォーム形式は、各プラットフォームが発行するURL埋め込み型のトークンで認証されるため、署名検証は使いません。

Raw

バックエンドで POST application/json を受け付けるHTTPSエンドポイントを用意します。
URLを Endpoint URL に貼り付けます。
保存後、Webhook詳細ページを開き Signing Public Key（署名公開鍵）をコピーします。配信検証に使います（API Reference — Webhooks を参照）。

飛書 / Lark

Lark（飛書）のグループに カスタムボット を追加し、そのWebhook URLをコピーします。
URLは https://open.feishu.cn/open-apis/bot/v2/hook/<hook-id> の形式です（海外リージョンは open.larksuite.com/... ですが、どちらでも動作します）。
URLを Endpoint URL に貼り付けます。

Slack

Slackワークスペースで宛先チャンネル向けに Incoming Webhook をインストールします。
Webhook URLをコピーします。形式は https://hooks.slack.com/services/T.../B.../<token> です。
URLを Endpoint URL に貼り付けます。

Discord

宛先チャンネルで チャンネルを編集 → 連携サービス → ウェブフック → 新しいウェブフック を開き、URLをコピーします。
形式：https://discord.com/api/webhooks/<id>/<token>。
URLを Endpoint URL に貼り付けます。

Telegramでは Bot Token と Chat ID の両方が必要です。Telegramの sendMessage URLはWaffoが自動で組み立てます。

@BotFather と会話してボットを作成（または既存のものを選択）し、トークンをコピーします。例：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11。
宛先のチャットまたはチャンネルにボットを追加し、メッセージ送信権限を付与します。
Chat IDを取得します。簡単な方法：そのチャットにメッセージを1通送信してから https://api.telegram.org/bot<TOKEN>/getUpdates にアクセスし、レスポンスの chat.id をコピーします。
Webhookを追加 のモーダルで Telegram を選び、Bot Token と Chat ID を貼り付けて保存します。

裏側ではWaffoが https://api.telegram.org/bot<TOKEN>/sendMessage に対して、指定された値を chat_id にセットしてPOSTします。

OpenClaw / Hermes（Pancakeプラグイン）

Pancakeプラグインは、Waffoのセルフホスト型リレーです。Waffoからイベントを受け取り、独自ロジック（テンプレート、レート制限、マルチファンアウト）を実行し、任意の宛先へ転送します。OpenClaw と Hermes は同プラグインの2種類のすぐ使えるフレーバーで、スタックに合う方を選んでください。

対応するセットアップコマンドでプラグインをインストールします：
```
# OpenClaw
npx -p @waffo/pancake-plugin openclaw-setup

# Hermes
npx -p @waffo/pancake-plugin hermes-setup
```
フルセットアップガイド：github.com/waffo-com/waffo-pancake-plugin
インストール後、https://relay.waffo.ai/webhook/<webhook-id> の形式のリレーURLが発行されます。
Webhookを追加 モーダルで OpenClaw / Hermes を選び、リレーURLを貼り付けて保存します。

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

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

注文イベント

イベント	トリガータイミング	一般的なアクション
`order.completed`	注文が完了	商品を配信、アクセスを付与

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

イベント	トリガータイミング	一般的なアクション
`subscription.activated`	サブスクリプションがアクティブ化	アカウント作成、制限設定
`subscription.payment_succeeded`	サブスクリプション課金成功	アクセス期間を延長
`subscription.updated`	サブスクリプション詳細が変更	アクセスレベルを更新
`subscription.canceling`	キャンセルがリクエストされた	チームに通知、リテンションオファーを送信
`subscription.uncanceled`	サブスクリプションが再アクティブ化	フルアクセスを復元
`subscription.canceled`	サブスクリプションが完全に終了	アクセスを取り消し
`subscription.past_due`	支払いが失敗	顧客に通知、リトライ

返金イベント

イベント	トリガータイミング	一般的なアクション
`refund.succeeded`	返金処理が成功	アクセスを取り消し、記録を更新
`refund.failed`	返金処理が失敗	マーチャントに通知、調査

ステップ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のテスト

テストWebhook URLを設定

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

テスト購入を行う

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

受信を確認

サーバーログを確認して、Webhookが正しく受信・処理されたことを確認。

ngrok を使ったローカル開発

ローカルで webhook ハンドラーを開発しているとき、Pancake のサーバーから http://localhost:3000 には直接アクセスできません。受信リクエストをローカルポートに転送する公開 HTTPS トンネルが必要です。ngrok を推奨します — 開発用途は無料で、すべてのカスタムヘッダー（X-Waffo-Signature を含む）を保持します。

なぜトンネルが必要か

Webhook 配信はサーバーへの受信です：Pancake が設定した URL に対して POST します。localhost のアドレスは自分のマシンからしかアクセスできないため、トンネルがないとリクエストは届きません。トンネルは開発セッションの間、ローカルサーバーに公開可能な HTTPS ホスト名を提供します。

ngrok のインストールと起動

インストール

macOS：brew install ngrok
Windows / Linux：ngrok.com/download からダウンロード

認証（無料プランで OK）

ngrok.com でサインアップし、ダッシュボードから authtoken を取得して以下を実行：

ngrok config add-authtoken <your-authtoken>

トンネルを起動

ローカルサーバーのポートに ngrok を向けます。webhook ハンドラーが localhost:3000 で動いている場合：

ngrok http 3000

ngrok は次のような転送 URL を出力します：

Forwarding  https://abc-123-456-789.ngrok-free.app -> http://localhost:3000

https://...ngrok-free.app の URL をコピーします — これがあなたの公開 webhook エンドポイントです。

Pancake への接続

Test Webhook URL を設定

マーチャントダッシュボードでストアを開き、Settings → Webhooks に移動。ngrok URL（ハンドラーパスを付けたもの、例：https://abc-123.ngrok-free.app/api/webhooks/waffo）を Test Webhook URL に貼り付け、受信したいイベントを選択して保存します。

ngrok URL は Test 環境にのみ設定してください。一時的なトンネル URL を Production webhook には絶対に設定しないでください — 本番トラフィックは安定的にデプロイされたエンドポイントに到達する必要があります。

イベントを発火

ダッシュボードで Send test event をクリックするか、Test モードで実際のアクション（テストカードでチェックアウトを完了するなど）を実行します。

リクエストを確認

ngrok のローカル web インスペクタ http://127.0.0.1:4040 を開きます — ヘッダーとボディを含むすべての通過リクエストが表示されます。X-Waffo-Signature ヘッダーが含まれていることを確認してください。

ハンドラーで検証

ローカルサーバーのログを確認します。webhook の POST が到着し、verifyWebhook() が成功するはずです。検証が失敗する場合は下の「よくある落とし穴」を参照してください。

よくある落とし穴

症状	原因	対処
localtunnel で常に署名検証が 401	localtunnel はカスタム HTTP ヘッダーを取り除くため、`X-Waffo-Signature` がハンドラーに届かない	ngrok か cloudflared を使ってください — どちらもすべてのヘッダーを保持します
再起動後に ngrok URL が変わった	無料プランでは `ngrok http` を実行するたびに新しいランダムサブドメインが発行される	起動のたびにダッシュボードの Test Webhook URL を更新してください。頻繁に開発する場合は、ngrok 有料プランの予約サブドメインを検討
しばらくするとイベントが届かなくなる	無料 ngrok セッションは数時間で期限切れになる	`ngrok http 3000` を再起動し、新しい URL を貼り直す
Pancake が同じイベントを複数回再送している	ハンドラーが 2xx 以外を返したため、指数バックオフで再試行された	ハンドラーを修正したのち、次の再試行を待つか、ダッシュボードの webhook delivery log で Resend をクリック

Cloudflared という代替

アカウント不要の選択肢が好みなら、cloudflared も同様に使えます：

cloudflared tunnel --url http://localhost:3000

ヘッダーを保持し、その場限りのトンネルなら登録不要、*.trycloudflare.com 形式の URL を出力するのでそのままダッシュボードに貼れます。トレードオフはリクエストインスペクタ UI が組み込まれていないこと — 自前のサーバーログに頼ることになります。

動作確認チェックリスト

ローカルサーバーが起動し、想定ポートで listen している
ngrok http <port> が動作中、転送 URL を控えた
ダッシュボードの Test Webhook URL が現在の ngrok URL（ハンドラーパス含む）と一致
http://127.0.0.1:4040 で入信リクエストが見え、X-Waffo-Signature ヘッダーが付いている
ローカルログに verifyWebhook 成功とイベントハンドラー実行が出ている

ベストプラクティス

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

チェックリスト

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

AI インテグレーション

ビジネスモデル

運用

Webhookとは？

ステップ1：DashboardでWebhookを追加

ペイロード形式を選ぶ

Raw

飛書 / Lark

Slack

Discord

Telegram

OpenClaw / Hermes（Pancakeプラグイン）

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

注文イベント

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

返金イベント

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

マーチャント通知

顧客通知

Webhookの仕組み

リトライポリシー

開発者向け：コード統合

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

2. 署名を検証

3. イベントを処理

4. 迅速に応答

Webhookのテスト

ngrok を使ったローカル開発

なぜトンネルが必要か

ngrok のインストールと起動

Pancake への接続

よくある落とし穴

Cloudflared という代替

動作確認チェックリスト

ベストプラクティス

チェックリスト

次のステップ

返金を管理

APIリファレンス — Webhooks

AI インテグレーション

ビジネスモデル

運用

Documentation Index

​Webhookとは？

​ステップ1：DashboardでWebhookを追加

​ペイロード形式を選ぶ

​Raw

​飛書 / Lark

​Slack

​Discord

​Telegram

​OpenClaw / Hermes（Pancakeプラグイン）

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

​注文イベント

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

​返金イベント

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

​マーチャント通知

​顧客通知

​Webhookの仕組み

​リトライポリシー

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

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

​2. 署名を検証

​3. イベントを処理

​4. 迅速に応答

​Webhookのテスト

​ngrok を使ったローカル開発

​なぜトンネルが必要か

​ngrok のインストールと起動

​Pancake への接続

​よくある落とし穴

​Cloudflared という代替

​動作確認チェックリスト

​ベストプラクティス

​チェックリスト

​次のステップ

返金を管理

APIリファレンス — Webhooks

Webhookとは？

ステップ1：DashboardでWebhookを追加

ペイロード形式を選ぶ

Raw

飛書 / Lark

Slack

Discord

Telegram

OpenClaw / Hermes（Pancakeプラグイン）

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

注文イベント

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

返金イベント

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

マーチャント通知

顧客通知

Webhookの仕組み

リトライポリシー

開発者向け：コード統合

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

2. 署名を検証

3. イベントを処理

4. 迅速に応答

Webhookのテスト

ngrok を使ったローカル開発

なぜトンネルが必要か

ngrok のインストールと起動

Pancake への接続

よくある落とし穴

Cloudflared という代替

動作確認チェックリスト

ベストプラクティス

チェックリスト

次のステップ