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.


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)

const isValid = timingSafeEqual(

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": {}


collecting_documentCollection document lifecycle event.
collecting_document_refundCollection document refund lifecycle event.
payment_documentPayment document lifecycle event.
payment_document_refundPayment document refund lifecycle event.
awaiting_consentInitiationAwaiting consent from end user.
awaiting_paymentInitiation/Payment BatchAwaiting payment to be made.
canceledPix Key/Pix QRCode/Pix Static QRCodeCanceled and cannot be used any longer.
confirmedPix Key/Pix QRCode/Pix Static QRCodeConfirmed and can now be used.
createdAllProcess has started.
failedPayIn/PayOutThe process has failed due to timeout or other specific errors.
refundedPayIn/PayOutA manual or automatic refund has taken place.
registeredPayIn/PayOutThe transaction has been successfully registered.
registeringPayIn/PayOutThe transaction is pending registration.
rejectedPayOutPayment has been rejected.
reversedPayOutThis payment has been reversed due to the selected account or the tax number's status.
sentPaymentBatchThe lines of this batch have been sent successfully.
settledPayIn/PayOutLiquidation/payment has been completed successfully.