メインコンテンツへスキップ
バージョン: 最新版

イベント API

イベント APIは、Omiseアカウント内のアクティビティログとWebhookイベント履歴へのアクセスを提供します。イベントは、成功した請求、失敗した決済、異議申し立ての作成など、アカウント内で発生するアクションを表します。

概要​

イベントは、アカウント内で重要な出来事が発生するたびに作成されます。以下を提供します:

  • 完全なアクティビティ履歴 - アカウント内のすべてのアクションを追跡
  • Webhookのデバッグ - Webhookに送信されたデータを正確に確認
  • 監査証跡 - コンプライアンスのためにアカウントアクティビティを監視
  • 統合テスト - Webhook処理ロジックを検証
  • リアルタイム監視 - 決済フローとシステムイベントを追跡

イベントの仕組み​

  1. イベントの作成 - アクション発生時（例: 請求成功）にOmiseがイベントを作成
  2. イベントの保存 - イベントは保存され、イベント API経由で利用可能になります
  3. Webhook配信 - イベントは設定されたWebhookエンドポイントに送信されます
  4. イベントの取得 - デバッグと監視のためにAPI経由でイベントを取得できます

イベントの構造​

各イベントには以下が含まれます:

  • イベントタイプ - 何が発生したか（例: charge.create、charge.complete）
  • イベントデータ - 変更された完全なオブジェクト（請求、返金、異議申し立てなど）
  • タイムスタンプ - イベントが発生した日時
  • Webhookステータス - Webhookが正常に配信されたかどうか

一般的なイベントタイプ​

請求イベント​

  • charge.create - 新しい請求が作成されました
  • charge.complete - 請求が正常に完了しました
  • charge.update - 請求が更新されました（例: 確定）

返金イベント​

  • refund.create - 返金が処理されました

顧客イベント​

  • customer.create - 新しい顧客が作成されました
  • customer.update - 顧客情報が更新されました
  • customer.destroy - 顧客が削除されました

送金イベント​

  • transfer.create - 送金が開始されました
  • transfer.update - 送金が更新されました
  • transfer.destroy - 送金が失敗またはキャンセルされました

異議申し立てイベント​

  • charge.dispute.create - 請求に対する異議申し立てが提出されました
  • charge.dispute.update - 異議申し立てのステータスが変更されました
  • charge.dispute.close - 異議申し立てが解決されました（勝訴または敗訴）

ソースイベント​

  • source.create - 決済ソースが作成されました（PromptPay、TrueMoneyなど）
  • source.update - ソースのステータスが更新されました（例: pending → successful）
  • source.failed - ソースの決済が失敗しました
  • source.successful - ソースの決済が成功しました

リンクイベント​

  • link.create - 決済リンクが作成されました
  • link.payment.create - リンク経由で決済が行われました
  • link.payment.complete - リンク決済が完了しました

受取人イベント​

  • recipient.create - 受取人が作成されました
  • recipient.update - 受取人の詳細が更新されました（検証、銀行口座）
  • recipient.verify - 受取人が検証され、送金を受け取る準備が整いました
  • recipient.destroy - 受取人が削除されました

スケジュールイベント​

  • schedule.create - 定期スケジュールが作成されました
  • schedule.suspend - スケジュールが一時停止されました
  • schedule.activate - スケジュールが再開されました
  • schedule.destroy - スケジュールが削除されました

発生イベント（スケジュール実行）​

  • schedule.occurrence.scheduled - 発生が実行待ちキューに追加されました
  • schedule.occurrence.successful - スケジュールされた操作が成功しました
  • schedule.occurrence.failed - スケジュールされた操作が失敗しました

Webhook配信イベント​

  • webhooks.deliver - Webhook配信試行が行われました
  • webhooks.retry - Webhook配信が再試行されました

主要なユースケース​

Webhookのデバッグ​

イベントを取得して、Webhookに送信されたデータを正確に確認し、配信問題をトラブルシューティングします。

アクティビティ監視​

最近のイベントを一覧表示して、アカウントアクティビティを監視し、異常なパターンを検出します。

統合テスト​

本番稼働前に、アプリケーションがさまざまなイベントタイプを正しく処理することを検証します。

監査ログ​

すべてのトランザクションとアカウント変更の完全な監査証跡を維持します。

利用可能なエンドポイント​

イベントの保持期間​

  • イベントは90日間保持されます
  • 古いイベントは自動的に削除されます
  • より長い保持期間が必要な場合は、定期的にイベントをエクスポートしてください

ベストプラクティス​

✅ 推奨事項​

  • Webhookを使用する - ポーリングの代わりにリアルタイムイベント処理にWebhookを使用
  • Webhook署名を検証する - イベントがOmiseからのものであることを確認
  • 重複イベントを処理する - Webhookは複数回送信される可能性があります
  • イベントIDをログに記録する - 処理済みのイベントを追跡
  • 冪等性を実装する - イベントIDに基づいて実装
  • Webhook失敗を監視する - イベント API経由で監視

❌ 避けるべきこと​

  • イベントを頻繁にポーリングしない - 代わりにWebhookを使用
  • イベントの順序を想定しない - イベントは順不同で到着する可能性があります
  • 署名検証をスキップしない - 常にWebhookの真正性を検証
  • イベントを二重処理しない - 処理前にイベントIDを確認

関連リソース​

サポートが必要ですか？ Webhooksガイドを確認するか、support@omise.coまでお問い合わせください