Webhooks

概要

Webhook は、イベントをリアルタイムでサーバーにプッシュします。ポーリングは不要です。

Waffo Pancake でイベント発生 --> あなたのエンドポイントに HTTP POST --> イベントを処理

セットアップ

HTTPS エンドポイントの作成

POST リクエストを受け付け、200 OK を返す、公開アクセス可能なエンドポイントを構築します。

ダッシュボードで登録

ダッシュボード > API と開発 > Webhooks に移動し、エンドポイント URL を追加します。

イベントの選択

受信するイベントを選択します。

保存

Webhook の設定を保存します。

イベントタイプ

イベントは、決済、サブスクリプション、返金のライフサイクル通知をカバーしています。ダッシュボードで Webhook を設定する際に、受信するイベントカテゴリを選択できます。

正確なイベント名と利用可能なカテゴリは、Webhook エンドポイントの設定時にダッシュボードに表示されます。最新のリストについてはダッシュボードをご参照ください。

ペイロード形式

各 Webhook 配信は、イベントタイプと関連データを含む JSON ボディの HTTP POST です：

{
  "event": "<event_type>",
  "data": {
    // イベント固有のフィールド
  }
}

全ての ID は UUID v4 形式です。金額は表示形式の文字列です（例：“29.00” = $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 'order.completed':
      handleOrderCompleted(data);
      break;
    case 'subscription.activated':
      handleSubscriptionActivated(data);
      break;
    case 'subscription.canceled':
      handleSubscriptionCanceled(data);
      break;
  }
});

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/waffo', methods=['POST'])
def handle_webhook():
    payload = request.get_json()
    event = payload.get('event')
    data = payload.get('data')

    if event == 'order.completed':
        handle_order_completed(data)
    elif event == 'subscription.activated':
        handle_subscription_activated(data)

    return jsonify({'received': True}), 200

冪等性

イベントは複数回配信される可能性があります。重複排除にはイベントデータを使用してください：

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 を記録してください

Get Started

Features

Merchant

Store

Merchant of Record

概要

セットアップ

イベントタイプ

ペイロード形式

Webhook の処理

冪等性

リトライポリシー

テスト

ベストプラクティス

​概要

​セットアップ

​イベントタイプ

​ペイロード形式

​Webhook の処理

​冪等性

​リトライポリシー

​テスト

​ベストプラクティス

概要

セットアップ

イベントタイプ

ペイロード形式

Webhook の処理

冪等性

リトライポリシー

テスト

ベストプラクティス