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

Read more about those limitations

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 .