ウェブフック イベント タイプ

Omise ウェブフック で利用可能なすべてのイベント タイプ、JSON ペイロード例、実装例の完全なリファレンス。

概要

Omise はアカウント 内 で発生 するイベント についてリアルタイム 通知を送信 します。各イベント タイプ は異なるデータ 構造を持つ固有 のペイロード を持ちます。

チャージ イベント

charge.create

チャージ がAPIを通じて、またはダッシュボード から作成 された時 にトリガー されます。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "charge.create",
  "created": 1234567890,
  "data": {
    "object": "charge",
    "id": "chrg_test_5xxxxxxxxxxxxx",
    "status": "pending",
    "amount": 100000,
    "currency": "THB",
    "description": "Test charge",
    "created": 1234567890,
    "updated": 1234567890
  }
}

charge.complete

チャージ が正常に完了 した時 にトリガー されます。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "charge.complete",
  "created": 1234567890,
  "data": {
    "object": "charge",
    "id": "chrg_test_5xxxxxxxxxxxxx",
    "status": "successful",
    "amount": 100000,
    "currency": "THB",
    "payment_status": "paid",
    "created": 1234567890,
    "paid": 1234567890
  }
}

charge.expire

チャージ が支払い なしで期限切れ になった時 にトリガー されます。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "charge.expire",
  "created": 1234567890,
  "data": {
    "object": "charge",
    "id": "chrg_test_5xxxxxxxxxxxxx",
    "status": "expired",
    "amount": 100000,
    "currency": "THB",
    "created": 1234567890,
    "expired": 1234567890
  }
}

払戻 イベント

refund.create

払戻 が作成 された時 にトリガー されます。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "refund.create",
  "created": 1234567890,
  "data": {
    "object": "refund",
    "id": "rfnd_test_5xxxxxxxxxxxxx",
    "charge": "chrg_test_5xxxxxxxxxxxxx",
    "amount": 50000,
    "currency": "THB",
    "status": "pending",
    "created": 1234567890
  }
}

顧客 イベント

customer.create

顧客 がAPI を通じて作成 された時 にトリガー されます。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "customer.create",
  "created": 1234567890,
  "data": {
    "object": "customer",
    "id": "cust_test_5xxxxxxxxxxxxx",
    "email": "customer@example.com",
    "description": "Test customer",
    "created": 1234567890
  }
}

customer.update

顧客 が更新 された時 にトリガー されます。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "customer.update",
  "created": 1234567890,
  "data": {
    "object": "customer",
    "id": "cust_test_5xxxxxxxxxxxxx",
    "email": "newemail@example.com",
    "updated": 1234567890
  }
}

customer.destroy

顧客 が削除 された時 にトリガー されます。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "customer.destroy",
  "created": 1234567890,
  "data": {
    "object": "customer",
    "id": "cust_test_5xxxxxxxxxxxxx",
    "deleted": true
  }
}

カード イベント

card.create

カード が顧客 に作成 された時 にトリガー されます。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "card.create",
  "created": 1234567890,
  "data": {
    "object": "card",
    "id": "card_test_5xxxxxxxxxxxxx",
    "brand": "Visa",
    "last_digits": "4242",
    "expiration_month": 12,
    "expiration_year": 2025,
    "created": 1234567890
  }
}

card.destroy

カード が削除 された時 にトリガー されます。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "card.destroy",
  "created": 1234567890,
  "data": {
    "object": "card",
    "id": "card_test_5xxxxxxxxxxxxx",
    "deleted": true
  }
}

転送 イベント

transfer.create

転送 が作成 された時 にトリガー されます。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "transfer.create",
  "created": 1234567890,
  "data": {
    "object": "transfer",
    "id": "trsf_test_5xxxxxxxxxxxxx",
    "amount": 900000,
    "currency": "THB",
    "status": "scheduled",
    "created": 1234567890
  }
}

transfer.pay

転送 が支払い されました イベント。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "transfer.pay",
  "created": 1234567890,
  "data": {
    "object": "transfer",
    "id": "trsf_test_5xxxxxxxxxxxxx",
    "amount": 900000,
    "currency": "THB",
    "status": "paid",
    "paid": 1234567890
  }
}

異議 イベント

dispute.create

異議 が作成 された時 にトリガー されます。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "dispute.create",
  "created": 1234567890,
  "data": {
    "object": "dispute",
    "id": "dspt_test_5xxxxxxxxxxxxx",
    "charge": "chrg_test_5xxxxxxxxxxxxx",
    "amount": 100000,
    "currency": "THB",
    "status": "open",
    "created": 1234567890
  }
}

dispute.update

異議 が更新 された時 にトリガー されます。

{
  "object": "event",
  "id": "evnt_test_5xxxxxxxxxxxxx",
  "key": "dispute.update",
  "created": 1234567890,
  "data": {
    "object": "dispute",
    "id": "dspt_test_5xxxxxxxxxxxxx",
    "status": "won",
    "updated": 1234567890
  }
}

イベント処理の実装

JavaScript でイベント を処理

// Node.js - イベント ハンドラー
const express = require('express');
const app = express();

app.post('/webhooks', express.json(), (req, res) => {
  const event = req.body;

  switch (event.key) {
    case 'charge.complete':
      handleChargeComplete(event.data);
      break;
    case 'charge.expire':
      handleChargeExpired(event.data);
      break;
    case 'refund.create':
      handleRefundCreated(event.data);
      break;
    case 'customer.create':
      handleCustomerCreated(event.data);
      break;
    case 'transfer.pay':
      handleTransferPaid(event.data);
      break;
    case 'dispute.create':
      handleDisputeCreated(event.data);
      break;
  }

  res.json({ received: true });
});

function handleChargeComplete(charge) {
  console.log(`Charge ${charge.id} completed: ${charge.amount} ${charge.currency}`);
  // 注文 ステータス を更新
  // 確認メール を送信
}

function handleRefundCreated(refund) {
  console.log(`Refund ${refund.id} created: ${refund.amount}`);
  // 払戻 ステータス を更新
}

Python でイベント を処理

# Flask - イベント ハンドラー
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks', methods=['POST'])
def handle_webhook():
    event = request.json

    event_handlers = {
        'charge.complete': handle_charge_complete,
        'charge.expire': handle_charge_expired,
        'refund.create': handle_refund_created,
        'customer.create': handle_customer_created,
        'transfer.pay': handle_transfer_paid,
        'dispute.create': handle_dispute_created,
    }

    handler = event_handlers.get(event.get('key'))
    if handler:
        handler(event.get('data', {}))

    return jsonify({'received': True})

def handle_charge_complete(charge):
    print(f"Charge {charge['id']} completed: {charge['amount']} {charge['currency']}")
    # 注文 ステータス を更新
    # 確認メール を送信

def handle_refund_created(refund):
    print(f"Refund {refund['id']} created: {refund['amount']}")
    # 払戻 ステータス を更新

Ruby でイベント を処理

# Rails - イベント ハンドラー
class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def omise
    event = JSON.parse(request.body.read)

    case event['key']
    when 'charge.complete'
      handle_charge_complete(event['data'])
    when 'charge.expire'
      handle_charge_expired(event['data'])
    when 'refund.create'
      handle_refund_created(event['data'])
    when 'customer.create'
      handle_customer_created(event['data'])
    when 'transfer.pay'
      handle_transfer_paid(event['data'])
    when 'dispute.create'
      handle_dispute_created(event['data'])
    end

    render json: { received: true }
  end

  private

  def handle_charge_complete(charge)
    puts "Charge #{charge['id']} completed: #{charge['amount']} #{charge['currency']}"
    # 注文 ステータス を更新
    # 確認メール を送信
  end

  def handle_refund_created(refund)
    puts "Refund #{refund['id']} created: #{refund['amount']}"
    # 払戻 ステータス を更新
  end
end

ベストプラクティス

1. イベント に タイムスタンプ を使用

イベント を作成時間 順 に処理 :

const events = [event1, event2, event3];
events.sort((a, b) => a.created - b.created);
events.forEach(event => handleEvent(event));

2. イベント を べき等 に処理

重複イベント を安全に処理 :

def handle_webhook(event):
    event_id = event['id']

    # すでに処理済み か どうかを確認
    if ProcessedEvent.objects.filter(event_id=event_id).exists():
        return  # スキップ

    # イベント を処理
    process_event(event)

    # 処理済み としてマーク
    ProcessedEvent.objects.create(event_id=event_id)

3. イベント を非同期 に処理

タイムアウト を避けるため バックグラウンド ジョブ で処理 :

class WebhooksController < ApplicationController
  def omise
    event = JSON.parse(request.body.read)

    # バックグラウンド ジョブ を排列
    ProcessWebhookJob.perform_later(event)

    # 迅速に レスポンス
    render json: { received: true }
  end
end

FAQ

イベント の順序 は保証 されますか?

いいえ。イベント は必ずしも作成順序 で配信 されません。タイムスタンプ を使用 してイベント を処理順 に確認してください。

イベント は複数回 配信 されますか?

はい、失敗した配信 では再試行 があります。イベント ID を追跡 してべき等処理 を実装してください。

ウェブフック ペイロード のサイズ は?

ペイロード は通常 100KB未満 です。1MB までのペイロード を処理 するようにエンドポイント をアップグレードしてください。

関連リソース

• セキュリティ - ウェブフック シグネチャ 検証
• 再試行 ロジック - イベント 再試行 とべき等
• ウェブフック テスト - ウェブフック テスト戦略
• API リファレンス - Omise API リファレンス

次のステップ

1. イベント タイプ のリスト をレビュー
2. 各 イベント タイプ のペイロード を確認
3. イベント ハンドラー を実装
4. シグネチャ 検証 を追加
5. べき等 処理 を実装
6. ウェブフック をテスト