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
Universally unique identifier (UUID) per the event object.

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":[
    ...
   ]
}