# Introduction
When a specific event occurs, a HTTP request is sent from our infrastructure to an 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 events notification (no need to periodically check the API for changes).
As a result, webhooks allow you to better handle:
- The intrisic impredictability 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.
# 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 are not necessarily received in chronological order
Despite the fact webhooks are sent chronologically, Treezor cannot guarantee that your servers will receive them in the same order. You can 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) (opens new window) 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 trigerred by the creation of a transaction (transaction.create event).
While webhooks return JSON, they are provided with the text/plain mimetype .