Documentation Index
Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
SDK 内蔵の WebhookHandler を使用する
SDK の webhook().handleWebhook() メソッドの利用を強く推奨します。次の処理を自動的に行います。
- 署名検証
- JSON パースとイベントルーティング
- 応答ボディの構築と署名
const handler = waffo.webhook()
.onPayment((n) => handlePayment(n))
.onRefund((n) => handleRefund(n))
.onSubscriptionStatus((n) => handleSubscription(n))
.onSubscriptionChange((n) => handleChange(n));
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
const result = await handler.handleWebhook(req.body.toString(), req.headers['x-signature'] as string);
res.setHeader('X-SIGNATURE', result.responseSignature);
res.status(200).send(result.responseBody);
});
冪等な処理
Waffo は同じイベントを複数回配信する場合があります。処理ロジックが冪等であることを確認してください。
waffo.webhook().onPayment(async (notification) => {
const orderId = notification.acquiringOrderId;
const order = await db.order.findByAcquiringOrderId(orderId);
if (order.status === 'PAY_SUCCESS') {
return;
}
await updateOrderStatus(orderId, notification.orderStatus);
});
高速な応答
- SDK はハンドラーの実行完了後に自動的に応答を構築します
- 時間のかかる処理 (メール送信、外部システムの更新など) は非同期で処理してください
- ハンドラー内で例外がスローされると、SDK は自動的に失敗応答を返します
セキュリティ
- 必ず
X-SIGNATURE を検証してください (SDK が自動で処理します)
- HTTPS エンドポイントを使用してください
- イベントを処理する前に署名を検証してください。検証が通る前にビジネスロジックを実行しないでください
- 応答には
X-SIGNATURE ヘッダーを含めてください (SDK が自動で処理します)
