Webhookイベントタイプ

Omise Webhookで利用可能なすべてのイベントタイプ、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を追跡してべき等処理を実装してください。

Webhookペイロードのサイズは?

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

関連リソース

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

次のステップ

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