Skip to main content
Version: 2019-05-29 (Current)

Events API

The Events API provides access to activity logs and webhook event history in your Omise account. Events represent actions that occur in your account, such as successful charges, failed payments, dispute creation, and more.

Overviewโ€‹

Events are created whenever something significant happens in your account. They provide:

  • Complete activity history - Track all actions in your account
  • Webhook debugging - See exactly what was sent to your webhooks
  • Audit trail - Monitor account activity for compliance
  • Integration testing - Verify your webhook handling logic
  • Real-time monitoring - Track payment flows and system events

How Events Workโ€‹

  1. Event Creation - Omise creates an event when an action occurs (e.g., charge succeeds)
  2. Event Storage - Events are stored and available via the Events API
  3. Webhook Delivery - Events are sent to your configured webhook endpoints
  4. Event Retrieval - You can retrieve events via API for debugging and monitoring

Event Structureโ€‹

Each event contains:

  • Event Type - What happened (e.g., charge.create, charge.complete)
  • Event Data - The complete object that changed (charge, refund, dispute, etc.)
  • Timestamp - When the event occurred
  • Webhook Status - Whether webhooks were delivered successfully

Common Event Typesโ€‹

Charge Eventsโ€‹

  • charge.create - New charge created
  • charge.complete - Charge successfully completed
  • charge.update - Charge updated (e.g., captured)

Refund Eventsโ€‹

  • refund.create - Refund processed

Customer Eventsโ€‹

  • customer.create - New customer created
  • customer.update - Customer information updated
  • customer.destroy - Customer deleted

Transfer Eventsโ€‹

  • transfer.create - Transfer initiated
  • transfer.update - Transfer updated
  • transfer.destroy - Transfer failed or cancelled

Dispute Eventsโ€‹

  • charge.dispute.create - Dispute filed against charge
  • charge.dispute.update - Dispute status changed
  • charge.dispute.close - Dispute resolved (won or lost)

Source Eventsโ€‹

  • source.create - Payment source created (PromptPay, TrueMoney, etc.)
  • source.update - Source status updated (e.g., pending โ†’ successful)
  • source.failed - Source payment failed
  • source.successful - Source payment succeeded
  • link.create - Payment link created
  • link.payment.create - Payment made through link
  • link.payment.complete - Link payment completed

Recipient Eventsโ€‹

  • recipient.create - Recipient created
  • recipient.update - Recipient details updated (verification, bank account)
  • recipient.verify - Recipient verified and ready to receive transfers
  • recipient.destroy - Recipient deleted

Schedule Eventsโ€‹

  • schedule.create - Recurring schedule created
  • schedule.suspend - Schedule paused
  • schedule.activate - Schedule resumed
  • schedule.destroy - Schedule deleted

Occurrence Events (Schedule Executions)โ€‹

  • schedule.occurrence.scheduled - Occurrence queued to run
  • schedule.occurrence.successful - Scheduled operation succeeded
  • schedule.occurrence.failed - Scheduled operation failed

Webhook Delivery Eventsโ€‹

  • webhooks.deliver - Webhook delivery attempt made
  • webhooks.retry - Webhook delivery retried

Key Use Casesโ€‹

Webhook Debuggingโ€‹

Retrieve events to see exactly what data was sent to your webhooks and troubleshoot delivery issues.

Activity Monitoringโ€‹

List recent events to monitor account activity and detect unusual patterns.

Integration Testingโ€‹

Verify that your application correctly handles various event types before going live.

Audit Loggingโ€‹

Maintain a complete audit trail of all transactions and account changes.

Available Endpointsโ€‹

Event Retentionโ€‹

  • Events are retained for 90 days
  • Older events are automatically deleted
  • Export events regularly if you need longer retention

Best Practicesโ€‹

โœ… Do Thisโ€‹

  • Use webhooks for real-time event handling instead of polling
  • Verify webhook signatures to ensure events are from Omise
  • Handle duplicate events - webhooks may be sent multiple times
  • Log event IDs to track which events you've processed
  • Implement idempotency based on event IDs
  • Monitor webhook failures via the Events API

โŒ Don't Do Thisโ€‹

  • Don't poll for events frequently - use webhooks instead
  • Don't assume event order - events may arrive out of sequence
  • Don't skip signature verification - always validate webhook authenticity
  • Don't process events twice - check event IDs before processing

Need help? Check our Webhooks Guide or contact support@omise.co