Webhook - 処理のベストプラクティス

​

SDK 内蔵の WebhookHandler を使用する

• 署名検証
• 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.status(200).send(result.responseBody);
});

​

冪等な処理

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);
});

​

配信順序ではなく最終状態で処理する

• コールバックの到着順序だけで最終的なビジネス状態を更新しないでください
• イベントの粒度に応じて、イベント ID や業務注文 ID などの冪等性キーを選んでください。期間ごとの利用権には subscriptionId と期間を組み合わせ、後続の期間を処理対象から除外しないようにしてください
• SUBSCRIPTION_STATUS_NOTIFICATION と SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION の両方をサブスクライブする場合は、いずれかのコールバックを受信した後に POST /api/v1/subscription/inquiry を呼び出し、その最終照会結果にもとづいて単一のサブスクリプション処理フローを実行してください

​

Subscription の利用権付与

• Subscription、期間、金額が対象プランと当該期間の請求額に一致することを確認してください
• 当該期間の決済成功と検証の完了を確認してから、対応する利用権を付与してください
• Subscription と期間ごとに利用権の付与結果を記録し、通知が重複しても再付与しないでください
• PAYMENT_NOTIFICATION を処理する際は、まず result.subscriptionInfo.subscriptionEvent で期間課金、決済手段の追加、差額課金を区別してください。後者 2 つを新しい期間の利用権付与の根拠にしないでください。値の説明は Subscription の決済イベントを参照してください

​

高速な応答

• SDK はハンドラーの実行完了後に自動的に応答を構築します
• 時間のかかる処理 (メール送信、外部システムの更新など) は非同期で処理してください
• ハンドラー内で例外がスローされると、SDK は自動的に失敗応答を返します

​

セキュリティ

• 必ず X-SIGNATURE を検証してください (SDK が自動で処理します)
• HTTPS エンドポイントを使用してください
• イベントを処理する前に署名を検証してください。検証が通る前にビジネスロジックを実行しないでください