Skip to content

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:

Info icon

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.

Info icon

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

AttributeDescription
webhookName of the webhook
webhook_idUnique identifier of the webhook (UUID v4, 36-character long string)
webhook_created_atDate at which the webhook was created, as Unix epoch (timestamp) in the form 10^-4 seconds
objectName of the Treezor object
object_idID of the Treezor object
object_payloadStandard Treezor objects (Payin, Payout, CardTransaction, User, Wallet, etc.), generally in an array
object_payload_signatureHash of [payload + webhook_secret]. This field allows you to ensure the payload originates from Treezor and has not been tempered with.
Bulb icon

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 .