Webhook は、イベントをリアルタイムでサーバーにプッシュします。ポーリングは不要です。
Waffo Pancake でイベント発生 --> あなたのエンドポイントに HTTP POST --> イベントを処理
セットアップ
HTTPS エンドポイントの作成
POST リクエストを受け付け、200 OK を返す、公開アクセス可能なエンドポイントを構築します。
ダッシュボードで登録
ダッシュボード > 開発者 > Webhooks に移動し、エンドポイント URL を追加します。
イベントタイプ
イベントは、決済、サブスクリプション、返金のライフサイクル通知をカバーしています。ダッシュボードで Webhook を設定する際に、受信するイベントカテゴリを選択できます。
正確なイベント名と利用可能なカテゴリは、Webhook エンドポイントの設定時にダッシュボードに表示されます。最新のリストについてはダッシュボードをご参照ください。
ペイロード形式
各 Webhook 配信は、イベントタイプと関連データを含む JSON ボディの HTTP POST です：
{
"event": "<event_type>",
"data": {
// イベント固有のフィールド
}
}
全ての ID は UUID v4 形式です。金額は最小通貨単位で表されます（例：2900 = $29.00）。タイムスタンプは ISO 8601 UTC です。
Webhook の処理
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;
}
});
冪等性
イベントは複数回配信される可能性があります。重複排除にはイベントデータを使用してください：
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 をインメモリではなくデータベースに保存してください。
リトライポリシー
配信に失敗した場合、自動的にリトライされます。受信を確認するため、エンドポイントが速やかに 200 ステータスコードを返すようにしてください。
テスト
サンドボックス環境を使用して Webhook をテストできます：
- ダッシュボードでテストモードに切り替える
- 開発者 > Webhooks に移動する
- イベントをトリガーするアクションを実行する
- エンドポイントに届くイベントを確認する
Webhook はテストモードとライブモードの両方で発火します。エンドポイントで環境を区別できるようにしてください。
ベストプラクティス
- HTTPS を使用する — 本番の Webhook エンドポイントには必須です
- 速やかにレスポンスする — 30 秒以内に 200 を返してください
- 重複を処理する — ID を使って重複排除してください
- 非同期で処理する — 重い処理でレスポンスをブロックしないでください
- 全てログに記録する — デバッグのために受信した Webhook を記録してください
