Events
Events are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new Event object. For example, when an ACH debit succeeds, we create an ach_debit.confirmed event; and when an ACH debit is returned, we create an ach_debit.returned event. Note that some API requests may cause multiple events to be created. For example, if a customer submits an emandate_api source, you will receive both a source.submitted event and a mandate.active event.
Events occur when the state of another API resource changes. The state of that resource at the time of the change is embedded in the event's data field. For example, a ach_debit.confirmed event will contain the full GET ACH Debit API response of ach_debit, and a mandate.failed event will contain the full GET Mandate API response of mandate.
As with other API resources, you can use endpoints to retrieve an individual event or a list of events from the API. We also have a separate webhooks system for sending the Event objects directly to an endpoint on your server. Webhooks are managed in your account settings.
NOTE: Access to events through the Retrieve Event API is guaranteed only for 30 days.
The event object
ATTRIBUTES
|
Attribute
|
Description
|
|---|---|
id string
| Unique identifier for the object.
|
object string, value is "event"
| String representing the object's type. Objects of the same type share the same value.
|
created timestamp
| Time at which the object was created. Measured in seconds since the Unix epoch.
|
livemode boolean
| Has the value true if the object exists in live mode or the value false if the object exists in test mode.
|
data string
| Object containing data associated with the event. See child attributes below.
|
type string
| Description of the event (e.g., customer.created or ach_debit.rejected).
|
resource_id string
| ID of the underlying object.
|
webhook_sent boolean
| Has the value true if the webhook post has been attempted or the value false if the webhook post has not been attempted.
|
webhook_attempts integer
| The number of times the webhook post has been attempted.
|
webhook_notified boolean
| Has the value true if the webhook post was successful or the value false if the webhook post was unsuccessful.
|
Child attributes for data:
|
Attribute
|
Description
|
|---|---|
object hash
| Object containing the API resource relevant to the event. For example, a customer.created event will have a full customer object as the value of the object key.
|