Introduction
When a specific event occurs, an HTTP request is sent from our infrastructure to a URL of your choice and provides you with relevant information regarding that event.
A webhook is characterized by:
- The unique identifier of the webhook
- The callback URL – The URL receiving the event notification
- The event – The event triggering a webhook request
- The payload – The data passed along with the event
- The signature – A means of checking authenticity
Why use Webhooks?
Although optional, using webhooks is strongly recommended. They provide much quicker event notifications (no need to periodically check the API for changes).
As a result, webhooks allow you to better handle:
- The intrinsic unpredictability of some banking events such as:
- Receiving a card payment or money transfer,
- Blocked transfers due to AML/CFT suspicion
- Check cashing
- Card activation by a User
- The inherent delay of some actions such as requesting a KYC or Document review.
Information – Not all Webhooks are available in Sandbox
What does a Webhook look like?
It looks like a standard HTTP POST request.
Details regarding the event are embedded as a JSON array (object_payload
). A hash (object_payload_signature
) of the body allows you to assert the authenticity of the received information.
Information – Webhooks may not be received in chronological order
While Treezor sends webhooks chronologically, there is no guarantee your servers receives them in the same order. Compare the webhook_created_at
values against your locally stored values to know which is most recent.
Structure of a webhook
Attribute | Description |
---|---|
webhook | Name of the webhook |
webhook_id | Unique identifier of the webhook (UUID v4, 36-character long string) |
webhook_created_at | Date at which the webhook was created, as Unix epoch (timestamp) in the form 10^-4 seconds |
object | Name of the Treezor object |
object_id | ID of the Treezor object |
object_payload | Standard Treezor objects (Payin, Payout, CardTransaction, User, Wallet, etc.), generally in an array |
object_payload_signature | Hash of [payload + webhook_secret ]. This field allows you to ensure the payload originates from Treezor and has not been tempered with. |
Tip – Webhooks content matches the API's
Objects contained in the payload are identical to any other object retrieved from Treezor Connect API. They are simply embedded in an event object.
Example
Below is an example of a Webhook request.
It was triggered by the creation of a transaction (transaction.create
event).
json
{
"webhook":"transaction.create",
"webhook_id":"54350b79-9250-4e4e-bc0e-c2c01f6c43c6",
"object":"transaction",
"object_id":"16700",
"object_payload":{
"transactions":[
{
"transactionId":"16700",
[...] // some attributes are hidden for clarity
}
]
},
"object_payload_signature":"XWvC\/4wAhkqIOgHAccHTkZQ73zp7QMBZC5APTU5oZww="
}
While webhooks return JSON, they are provided with the text/plain
mime type .