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 a transaction is created, we create a transaction.created event; and when a contract is updated, we create an contract.changed event. Note that many API requests may cause multiple events to be created. For example, if you create a new contract for a customer, you will receive both a customer.created event and a contract.created 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 content field. For example, a transaction.changed will contain a transaction object, and a contract.changed event will contain a contract object.
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. Your webhook URL is managed in your account options.
Important Note: Events that are delivered successfully are kept in storage for 24 hours after submission, Events that are undelivered after 15 attempts are stored for 30 days after which they are permanently trashed. When an event fails, our system will retry the submission once every 3 minutes, after 15 attempts it will give up.
The Event Object
| Attributes | ||
| id string |
|
|
| entity_id string |
The UUID of the object that triggered the event. | |
| name string |
The name of the event in the format: object.event, for example; transaction.changed | |
| delivery_to string |
The URL that the payload will/has been submitted to. Returns an empty string if no URL has been configured in which case the event will not be submitted but rather stored for 30 days. | |
| content string |
Object that triggered the event, this will be a full payload object. This object is submitted to the server. | |
| delivered boolean |
Boolean indicated whether the event was submitted to the destination server successfully. | |
| response_content extended length string |
Raw text result of the response received from the server, if any. | |
| response_code integer |
Raw HTTP response code received from the server when the content was delivered or failed to deliver. | |
| retries integer |
The number of times the event attempted to resubmit to the server. Returns 0 if the first attempt succeeds. | |
| submitted_at timestamp |
The timestamp at which the most recent attempt was submitted. | |
| created_at timestamp |
The timestamp at which the event was created. |
Events are submitted to the merchants configured notify_url (configured on the merchant console under account options) as a standard HTTP POST request with all Event attributes as the POST body. If the webhook submission of the event does not succeed, the API may be utilised to retrieve all recent events and each event object will contain information on why the request failed including the HTTP response code and HTTP response body.
Supported Events
| Event Names | |
| transaction.created Transaction Creation |
Fired when a new transaction object is created. |
| transaction.changed Transaction Attribute Changed |
Fired when one or more transaction attributes are changed including the status. |
| transaction.deleted Transaction Deleted |
Fired when a transaction is deleted either by the system or via the API. |
| contract.created Contract Creation |
Fired when a new contract object is created. |
| contract.changed Contract Attribute Changed |
Fired when one or more contract attributes are changed including the status. |
| contract.deleted Contract Deleted |
Fired when a contract is deleted either by the system or via the API. |
| customer.created Customer Creation |
Fired when a new customer object is created. A customer is a Client's end user (such as a Gym Member) |
| customer.changed Customer Updated |
Fired when one or more customer attributes are changed. |
| customer.deleted Customer Deleted |
Fired when a transaction is deleted either by the system or via the API. |
| mandate.created Mandate Created |
Fired when a new mandate object is created. |
| mandate.changed Mandate Attribute Changed |
Fired when a mandate is updated via the API, the customer or the system. |
| mandate.deleted Mandate Deleted |
Fired when a mandate is deleted either by the system or via the API. |
Get a list of events
GET /v2/events/
Request
curl -s \ --header "Content-Type: application/json" \ --header "Authorization: Token :token" \ --request GET "https://secure-test.addpay.co.za/v2/events/"
Response
{
"meta":{
"status":"success",
"message":"OK",
"code":200,
"pagination":{
"records":2,
"page":1,
"pages":1,
"limit":"10"
}
},
"data":[
...
]
}