Working with Webhooks

Most of transactions at Trio's integration are asynchronous, which means that we have some process in background to finish and commit the transaction. In order to effective communicate with external systems and customers we use webhooks.

The webhooks can be configured through our API or using our management console.

Technical details

All registered endpoints must be configured to receive a HTTP POST with JSON payload. We have a default timeout configured of 3 seconds waiting a 2XX HTTP status code in order to mark the payload as delivered.

We have a special failure schema, our systems will try 5 times, with a retry configure for 16 seconds for the first failure and doubling the time each failure: 16s, 32s, 104s, 208s, etc.

We recommend that all registered endpoints uses the HTTPS protocol to secure the in-transit payload.

Authentication

When you create a webhook, it's necessary to fill the Secretfield, this information will be sent through as the HTTP header x-webhook-secret. You can use the to authenticate at you side.

And to verify that a webhook was actually sent by Trio, every payload is signed with a signature that is passed through as the HTTP header x-webhook-signature. The signature is encoded and can be replicated by applying HMAC-SHA-256 to the body of the webhook with your specific webhook key, which can be found in your webhook settings page. Below a simple example of how to generate the signature using Node.js:

import { createHmac, timingSafeEqual } from "crypto"

const expectedSignature = req.headers["x-webhook-signature"]
const algorithm = "sha256"
const signatureKey = "your_signature_key"
const message = JSON.stringify(req.body)

const computedSignature = createHmac(algorithm, signatureKey)
	.update(message)
	.digest("hex")
	.toUpperCase()

const isValid = timingSafeEqual(
	Buffer.from(expectedSignature), 
  Buffer.from(computedSignature)
)

Please contact support if your webhook key is accidentally made public. We will rotate the key and coordinate the change with you.

Content and Structure

All the webhooks notification sent by Trio uses the following structure:

• ref_id is the identification from the reference
• category specifies which category the event belongs
• type specifies the what type of event from the category

{
  "ref_id": "",
  "category": "",
  "type": "",
  "timestamp": "",
  "company_id": "",
  "data": {}
}

Events