> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook通知を設定
> 支払い成功、サブスクリプション更新、返金処理時に自動通知を受信
## Webhookとは？
Webhookは、イベントが発生した時にWaffo Pancakeがサーバーに自動送信する通知です — 支払い成功、サブスクリプション更新、返金処理など。
**Webhookが必要な理由：**
* **配信の自動化**：支払い後すぐにダウンロードリンクを送信したりアクセスを付与
* **システムの同期**：サブスクリプションステータス変更時にデータベースを更新
* **リアルタイム対応**：失敗した支払い、キャンセル、返金にリアルタイムで対応
***
## ステップ1：DashboardでWebhookを追加
Dashboardで **設定 → Webhooks** に移動します。
送信先に合わせてペイロードの形式を選びます。自前のバックエンドなら Raw JSON、Slack / Discord / Lark（飛書）/ Telegram などのチャットプラットフォーム形式を選べば、その先でそのまま自然に表示されます。あるいは **OpenClaw / Hermes**（セルフホストの Pancake プラグイン）を選んで独自ルーティングや下流処理に流すこともできます。詳細は下記の [ペイロード形式を選ぶ](#ペイロード形式を選ぶ) を参照。
Waffo Pancakeがイベント通知を送信する先のURLを入力します。
* **テストモードURL**：開発/ステージングサーバー（例：`https://staging.yoursite.com/webhooks/waffo`）
* **本番URL**：本番サーバー（例：`https://yoursite.com/webhooks/waffo`）
テストと本番で異なるURLを設定できます。テストイベントと実際のイベントを分離できます。
前のステップで **Telegram** を選んだ場合は、URLではなく **Bot Token** と **Chat ID** を入力します。取得方法は下記の [Telegram](#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/` |
| **Slack** | Incoming Webhook経由でSlackチャンネルに投稿したいとき。 | `https://hooks.slack.com/services/T.../B.../` |
| **Discord** | チャンネルWebhook経由でDiscordチャンネルに投稿したいとき。 | `https://discord.com/api/webhooks//` |
| **Telegram** | ボット経由でTelegramのチャットやグループに投稿したいとき。 | Bot Token + Chat ID（URLはWaffoが組み立て） |
| **OpenClaw / Hermes** | セルフホストの **Pancakeプラグイン** を経由してカスタム下流処理にルーティングしたいとき。 | `https://relay.waffo.ai/webhook/` |
RSA-SHA256署名が付くのは **Raw** だけです。チャットプラットフォーム形式は、各プラットフォームが発行するURL埋め込み型のトークンで認証されるため、署名検証は使いません。
### Raw
1. バックエンドで `POST application/json` を受け付けるHTTPSエンドポイントを用意します。
2. URLを **Endpoint URL** に貼り付けます。
3. **設定 → Webhooks** ページで、対象環境（Test または Production）の **Webhook Public Key**（検証用公開鍵）をそのままコピーします。配信検証に使います（[API Reference — Webhooks](/api-reference/webhooks) を参照）。この公開鍵は**プラットフォーム共通で、すべてのストアで同じ**です。今追加した Webhook とは無関係で、Webhook URL の追加・編集・削除があっても変わりません。
### 飛書 / Lark
1. Lark（飛書）のグループに **カスタムボット** を追加し、そのWebhook URLをコピーします。
2. URLは `https://open.feishu.cn/open-apis/bot/v2/hook/` の形式です（海外リージョンは `open.larksuite.com/...` ですが、どちらでも動作します）。
3. URLを **Endpoint URL** に貼り付けます。
### Slack
1. Slackワークスペースで宛先チャンネル向けに **Incoming Webhook** をインストールします。
2. Webhook URLをコピーします。形式は `https://hooks.slack.com/services/T.../B.../` です。
3. URLを **Endpoint URL** に貼り付けます。
### Discord
1. 宛先チャンネルで **チャンネルを編集 → 連携サービス → ウェブフック → 新しいウェブフック** を開き、URLをコピーします。
2. 形式：`https://discord.com/api/webhooks//`。
3. URLを **Endpoint URL** に貼り付けます。
### Telegram
Telegramでは **Bot Token** と **Chat ID** の両方が必要です。Telegramの `sendMessage` URLはWaffoが自動で組み立てます。
1. [@BotFather](https://t.me/botfather) と会話してボットを作成（または既存のものを選択）し、トークンをコピーします。例：`123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`。
2. 宛先のチャットまたはチャンネルにボットを追加し、メッセージ送信権限を付与します。
3. Chat IDを取得します。簡単な方法：そのチャットにメッセージを1通送信してから `https://api.telegram.org/bot/getUpdates` にアクセスし、レスポンスの `chat.id` をコピーします。
4. **Webhookを追加** のモーダルで **Telegram** を選び、**Bot Token** と **Chat ID** を貼り付けて保存します。
裏側ではWaffoが `https://api.telegram.org/bot/sendMessage` に対して、指定された値を `chat_id` にセットしてPOSTします。
### OpenClaw / Hermes（Pancakeプラグイン）
Pancakeプラグインは、Waffoのセルフホスト型リレーです。Waffoからイベントを受け取り、独自ロジック（テンプレート、レート制限、マルチファンアウト）を実行し、任意の宛先へ転送します。**OpenClaw** と **Hermes** は同プラグインの2種類のすぐ使えるフレーバーで、スタックに合う方を選んでください。
1. 対応するセットアップコマンドでプラグインをインストールします：
```bash theme={"system"}
# OpenClaw
npx -p @waffo/pancake-plugin openclaw-setup
# Hermes
npx -p @waffo/pancake-plugin hermes-setup
```
フルセットアップガイド：[github.com/waffo-com/waffo-pancake-plugin](https://github.com/waffo-com/waffo-pancake-plugin)
2. インストール後、`https://relay.waffo.ai/webhook/` の形式のリレーURLが発行されます。
3. **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](/ja/api-reference/webhooks)をご覧ください。
***
## Webhookのテスト
Dashboard → 設定 → Webhooksで、テストサーバーのURLを入力。
テストモードで購入を作成。テストURLにWebhookイベントがトリガーされます。
サーバーログを確認して、Webhookが正しく受信・処理されたことを確認。
***
## ngrok を使ったローカル開発
ローカルで webhook ハンドラーを開発しているとき、Pancake のサーバーから `http://localhost:3000` には直接アクセスできません。受信リクエストをローカルポートに転送する**公開 HTTPS トンネル**が必要です。[ngrok](https://ngrok.com) を推奨します — 開発用途は無料で、すべてのカスタムヘッダー（`X-Waffo-Signature` を含む）を保持します。
### なぜトンネルが必要か
Webhook 配信は**サーバーへの受信**です：Pancake が設定した URL に対して POST します。localhost のアドレスは自分のマシンからしかアクセスできないため、トンネルがないとリクエストは届きません。トンネルは開発セッションの間、ローカルサーバーに公開可能な HTTPS ホスト名を提供します。
### ngrok のインストールと起動
* **macOS**：`brew install ngrok`
* **Windows / Linux**：[ngrok.com/download](https://ngrok.com/download) からダウンロード
[ngrok.com](https://ngrok.com) でサインアップし、ダッシュボードから authtoken を取得して以下を実行：
```bash theme={"system"}
ngrok config add-authtoken
```
ローカルサーバーのポートに ngrok を向けます。webhook ハンドラーが `localhost:3000` で動いている場合：
```bash theme={"system"}
ngrok http 3000
```
ngrok は次のような転送 URL を出力します：
```
Forwarding https://abc-123-456-789.ngrok-free.app -> http://localhost:3000
```
`https://...ngrok-free.app` の URL をコピーします — これがあなたの公開 webhook エンドポイントです。
### Pancake への接続
マーチャントダッシュボードでストアを開き、**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 モードで実際のアクション（[テストカード](/ja/api-reference/webhooks#testing)でチェックアウトを完了するなど）を実行します。
ngrok のローカル web インスペクタ [http://127.0.0.1:4040](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](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) も同様に使えます：
```bash theme={"system"}
cloudflared tunnel --url http://localhost:3000
```
ヘッダーを保持し、その場限りのトンネルなら登録不要、`*.trycloudflare.com` 形式の URL を出力するのでそのままダッシュボードに貼れます。トレードオフはリクエストインスペクタ UI が組み込まれていないこと — 自前のサーバーログに頼ることになります。
### 動作確認チェックリスト
* [ ] ローカルサーバーが起動し、想定ポートで listen している
* [ ] `ngrok http ` が動作中、転送 URL を控えた
* [ ] ダッシュボードの Test Webhook URL が**現在の** ngrok URL（ハンドラーパス含む）と一致
* [ ] [http://127.0.0.1:4040](http://127.0.0.1:4040) で入信リクエストが見え、`X-Waffo-Signature` ヘッダーが付いている
* [ ] ローカルログに `verifyWebhook` 成功とイベントハンドラー実行が出ている
***
## ベストプラクティス
1. **迅速に応答**：すぐに200を返し、非同期で処理
2. **重複を処理**：イベントは複数回送信される可能性あり — 冪等な処理を実装
3. **署名を検証**：処理前に必ずWebhook署名を検証
4. **すべてを記録**：デバッグ用に受信したWebhookのログを保持
5. **失敗を監視**：Dashboardで失敗したWebhook配信を確認
***
## チェックリスト
* [ ] テスト・本番のWebhook URLを設定
* [ ] チームのメール通知を設定
* [ ] 顧客の通知設定を構成
* [ ] テストWebhookの受信と処理を確認
* [ ] 署名検証を実装（コード統合の場合）
***
## 次のステップ
返金リクエストの処理と返金状況の追跡
詳細なWebhookペイロード形式とコード例