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

Events API

Events APIは、Omiseアカウントのアクティビティログとwebhookイベント履歴へのアクセスを提供します。イベントは、成功した課金、失敗した支払い、紛争の作成など、アカウントで発生するアクションを表します。

概要​

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

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

イベントの仕組み​

  1. イベント作成 - アクションが発生したとき（例：課金成功）Omiseがイベントを作成
  2. イベント保存 - イベントは保存され、Events 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署名を検証 - イベントがOmiseからのものであることを確認
  • 重複イベントを処理 - webhookは複数回送信される可能性があります
  • イベントIDをログに記録 - 処理済みのイベントを追跡
  • 冪等性を実装 - イベントIDに基づいて実装
  • webhook失敗を監視 - Events APIで監視

避けるべきこと​

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

関連リソース​

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