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 Secret
field, 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 referencecategory
specifies which category the event belongstype
specifies the what type of event from the category
{
"ref_id": "",
"category": "",
"type": "",
"timestamp": "",
"data": {}
}
Events
Category | Description |
---|---|
collecting_document | Collection document lifecycle event. |
collecting_document_refund | Collection document refund lifecycle event. |
payment_document | Payment document lifecycle event. |
payment_document_refund | Payment document refund lifecycle event. |
Updated 8 days ago