Webhooks はイベントをリアルタイムでサーバーにプッシュします。ポーリング不要。
あなたのアプリ <-- Webhook <-- Waffo Pancake
セットアップ
エンドポイントを作成
POST リクエストを受け付ける HTTPS エンドポイントを構築。
イベントタイプ
| イベント | 説明 |
|---|
payment.completed | 支払い成功 |
payment.failed | 支払い失敗 |
subscription.created | 新規サブスクリプション開始 |
subscription.canceled | サブスクリプションキャンセル |
subscription.trial_ending | トライアルが3日後に終了 |
subscription.payment_failed | サブスクリプション課金失敗 |
refund.created | 返金チケット作成 |
refund.approved | 返金承認 |
ペイロードフォーマット
Webhook ペイロードは標準の Waffo Pancake API レスポンス形式に従います：
{
"event": "payment.completed",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"orderId": "660e8400-e29b-41d4-a716-446655440001",
"amount": 2900,
"currency": "USD",
"status": "completed",
"createdAt": "2026-01-15T10:30:00.000Z"
}
}
すべての ID は UUID v4 形式です。金額は最小通貨単位（例：2900 = $29.00）です。タイムスタンプは ISO 8601 UTC 形式です。
サブスクリプションイベントの例
{
"event": "subscription.created",
"data": {
"id": "770e8400-e29b-41d4-a716-446655440002",
"status": "active",
"billingPeriod": "monthly",
"amount": 2900,
"currency": "USD",
"currentPeriodEnd": "2026-02-15T10:30:00.000Z"
}
}
正しいレスポンス
すぐに 200 OK を返してください。重い処理が必要な場合は非同期で処理。
app.post('/webhooks/waffo', (req, res) => {
// 即座にレスポンス
res.status(200).send('OK');
// 非同期で処理
const { event, data } = req.body;
switch (event) {
case 'payment.completed':
handlePaymentCompleted(data);
break;
case 'subscription.created':
handleSubscriptionCreated(data);
break;
case 'subscription.canceled':
handleSubscriptionCanceled(data);
break;
}
});
リトライポリシー
失敗した配信は自動的にリトライされます：
| 試行回数 | 遅延 |
|---|
| 1 | 即時 |
| 2 | 5 分 |
| 3 | 30 分 |
| 4 | 2 時間 |
| 5 | 24 時間 |
冪等性
イベントは複数回配信される場合があります。イベントデータ（オーダーや支払い ID など）を使用して重複排除し、ハンドラーが各イベントを一度だけ処理するようにしてください。
const processedEvents = new Set();
app.post('/webhooks/waffo', (req, res) => {
const { event, data } = req.body;
const eventKey = `${event}:${data.id}`;
if (processedEvents.has(eventKey)) {
return res.status(200).send('Already processed');
}
processedEvents.add(eventKey);
res.status(200).send('OK');
// イベントを処理
processWebhook(event, data);
});
本番環境では、処理済みイベント ID をメモリではなくデータベースに保存して、サーバー再起動後も永続化してください。
ベストプラクティス
- HTTPS を使用 — 本番 Webhook エンドポイントの必須条件
- 素早くレスポンス — 30 秒以内に 200 を返す；重い処理は非同期で
- 重複を処理 — イベントはリトライされる可能性あり；ID で重複排除
- 非同期処理 — 重い処理でレスポンスをブロックしない
- すべてをログ — デバッグのために受信 Webhook を記録
テスト
テストモードを使用して Webhook エンドポイントにテストイベントを送信：
- ダッシュボードヘッダーでテストモードに切り替え
- 開発者 —> Webhooks に移動
- テストモードでアクション（注文作成、支払い完了）を実行
- エンドポイントで受信 Webhook イベントを確認
Webhook はテストモードとライブモードの両方で発火します。エンドポイントが元のアクションの X-Environment コンテキストを使用してテストとライブイベントを区別できることを確認してください。
デバッグ
ダッシュボードで Webhook 配信ログを確認：
- 配信ステータス（成功/失敗）
- エンドポイントからの HTTP レスポンスコード
- 送信されたペイロード
- タイムスタンプとリトライ回数
次のステップ
Webhook ガイド
ステップバイステップの Webhook 統合チュートリアル。
API リファレンス
完全な API ドキュメント。
