Webhooks

This service notifies you of all account activities.

A notification may be an activity creation or modification. To determine which case it is, read the 'type' field, which will have one of the following:

  • ACTIVITY_CREATED: We notify you when a new activity is created.
  • ACTIVITY_UPDATED: We notify you when an activity is modified. Activities may have their status changed from 'PENDING' to 'APPROVED' or from 'PENDING' to 'REJECTED'.

Digital signature request verification process

Along with the notification, we will send a set of HTTP headers to verify its authenticity.

The HTTP headers we send are:

  • x-api-key : this header allows you to identify which api-secret you have to use in the event that multiple api-key and api-secret pairs have been configured.

  • x-signature : this header contains the digital signature that you must verify to ensure request integrity. If the signature does not match, the order must be rejected.

  • x-timestamp : this header contains the moment the order was signed in unix-epoch format so that you can verify that the signature has not expired.

  • x-endpoint : the endpoint to which the request is made. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm that they match.

The digital signature is an HMAC-SHA256 code constructed using the 'api-secret' and a series of bytes, composed of a concatenation of the timestamp, endpoint and request body coded in UTF-8.

The following is a pseudo-code to verify that the digital signature of a request is legitimate:

requestSignature = request.headers['x-signature'] signatureData = encode(request.headers['x-timestamp'] + request.headers['x-endpoint'] + request.body , 'UTF-8') recreatedSignature = hmac(apiSecret, signatureData, 'SHA256') validSignature = requestSignature == recreatedSignature

Activity notification

The following endpoint must be in the client service so that it can receive the requests of the activities created/updated. If the request returns an HTTP code of type 2xx, it will not be sent again and will be marked as Sent correctly. Otherwise, we will try again.
Available parameters
Header Parameters
X-Api-Keystringrequired
This header lets you identify which api-secret you have to use in the event that multiple api-key and api-secret pairs have been configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (timestamp + endpoint + body) that you must verify to ensure request integrity. If the signature does not match, the order must be rejected.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
Este header contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas corroborar que la firma no expiró.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
This header is used to regenerate the signature to be checked. Compare it with the service endpoint to verify that they match.
Example: X-Endpoint: /client/api/activities/updates
Body Parameters
typestringrequired
Process type of the activity.
Example: ACTIVITY_CREATED
versionstringrequired
Version number of the event.
Example: 1.0.0
idempotency_keystringrequired
Idempotent identifier for creating the event.
Example: act-20I2tIqG3buTsvHKKORrtY2MkFH
datetimestring(format: date-time)required
Event creation date.
Example: 2021-12-31T23:59:59.999Z
activityobject
Was this section helpful to you?
POST/<url-del-cliente>
{
"type":
"ACTIVITY_CREATED"
"version":
"1.0.0"
"idempotency_key":
"act-20I2tIqG3buTsvHKKORrtY2MkFH"
"datetime":
"2021-12-31T23:59:59.999Z"
"activity":{
"account":{
...
}
"origin_tx_id":
"atx-200mVjWAnL8tD4vlG3fexiQeWvN"
"origin":
"string"
"process_type":
"string"
"type":
"string"
"data":{
...
}
"total_amount":
"1200.15"
"entry_type":
"DEBIT"
"result":
"string"
"rejection_reason":
"string"
"rejection_message":{
...
}
"forced":
true
"created_at":
"2021-12-31T23:59:59.999Z"
"updated_at":
"2021-12-31T23:59:59.999Z"
}
}
Response examples