Webhoook Event Notification

Notifications, often referred to as webhooks, provide a mechanism for applications to receive real-time updates about specific events. Within this API, webhooks are used to inform your server about a range of events, including transactions, refunds, or card tokenization, allowing your system to react promptly to these occurrences.

Security

To validate the authenticity of requests, we use a signature process. The API key is hashed using SHA-256 to generate a key, which is then used in a HMAC-SHA-256 operation to sign the timestamp (Sec-Timestamp header) and request body. The signature is then compared to the value sent in the Sec-Signature header. Additionally, after verifying the signature, you must retrieve the session object to ensure the accuracy and legitimacy of the event before further processing. Note that you should expect to receive multiple events and handle each one accordingly.

key = SHA256(secretAPIKey)
time = request.header.Get('Sec-Timestamp')
hmac = HMAC-SHA-256(time + request.body, key)
if hmac == request.header.Get('Sec-Signature') {
    echo "Signature is valid"
}    

Resending of notifications

The webhook must return a status code within the 2xx range. If a different status code is received, the system will make 4 retry attempts. After the 4th attempt, it will continue retrying with an exponential backoff for up to 3 days.

Webhoook Event Object

Field	Type	Description
id	string	Unique identifier for the event object.
type	enum	The event type is either “session.created”, “session.expired”, “session.completed”.
created_at	int	The timestamp at which the Session was created.
data.status	enum	The status of the session is either “open”, “expired”, or “completed”.
data.session_id	string	Unique identifier for the session object associated to the event.

Session Creation Notification

The "session.created" notification informs your system that a new session has been successfully created

The above event type returns JSON structured like this:

{
  "id": "AZIGaeLbem2YK9tJu-hlIg",
  "version": "0.1",
  "type": "session.created",
  "create_at": 1726684455,
  "data": {
    "session_id": "AZIGaeLRdVWAenLbf0FhyA",
    "status": "open"
  }
}

Session Complete Notification

The "session.completed" notification informs your system that a new session has been successfully completed

The above event type returns JSON structured like this:

{
  "id": "AZICl7zwcWy-RRgcTH0mbQ",
  "version": "0.1",
  "type": "session.completed",
  "create_at": 1726620351,
  "data": {
    "session_id": "AZIClyFieTev7xCi6JuXBQ",
    "status": "completed"
  }
}

Session Expire Notification

The "session.expired" notification informs your system that a new session has been expired

The above event type returns JSON structured like this:

{
  "id": "AZIF2O__eJSHRFuYCX18ag",
  "version": "0.1",
  "type": "session.expired",
  "create_at": 1726674956,
  "data": {
    "session_id": "AZIF2O-zdqO1BTTr6V0opw",
    "status": "expired"
  }
}