Content and structure

Every notification Trio sends has the same JSON structure: an envelope that says which event happened and to what, and a data object with the details of the resource involved. This page explains the envelope; the Events page lists what data contains for each category.

The envelope

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

Field	Description
`ref_id`	ID of the resource the event refers to: the document, refund, recurrence or entity.
`category`	Category the event belongs to, such as `in_document` or `out_document`.
`type`	Type of the event within the category, such as `created`, `settled` or `failed`.
`timestamp`	Timestamp of the event, in the format described in Date and time.
`data`	The resource in the state the event reports: the document, refund, recurrence or entity, with its own `id`.

The examples on the Events page carry a few more envelope fields, such as context_id and context_type. They are not needed to handle a notification.

Reading a notification

The notification below reports a cash-in document that settled: category and type say what happened, ref_id says to which document, and data carries the document itself. Amounts are in cents (BRL 100.00 = 10000), so this payment is BRL 1.00.

{
  "data": {
    "amount": {
      "amount": 100,
      "currency": "BRL"
    },
    "counterparty": {
      "id": "29b6d0bc-7226-483b-99aa-aa815521ebb0",
      "name": "Conta 002",
      "tax_number": "45865162797606"
    },
    "description": null,
    "end_to_end_id": "E49931906202501311822NX1S6J7KaOm",
    "id": "0194bd99-65cd-5ee9-70f6-44d61ae5aa41",
    "receipt_url": "https://receipts.sandbox.trio.com.br/019108db-d49f-c744-5b79-736a2849ddf5/in/0194bd99-65cd-5ee9-70f6-44d61ae5aa41",
    "transaction_date": "2025-01-31T18:22:14.510717Z",
    "document_type": "pix",
    "bank_account_id": "0194412c-c559-5452-942e-7f4b4975c666"
  },
  "timestamp": "2025-01-31T18:22:14.477163Z",
  "type": "settled",
  "category": "in_document",
  "ref_id": "0194bd99-65cd-5ee9-70f6-44d61ae5aa41"
}

To handle it:

Route on category and type. Together they name the event, in_document.settled here.
Find your own record with ref_id, or with data.external_id when you sent one in the request that created the resource.
Update that record from data. If you prefer to read the current state from the API, fetch the resource by ref_id.

Trio retries a notification your endpoint does not acknowledge in time, so the same event can arrive twice. Treat the combination of ref_id, category and type as the key of a notification and skip the ones you have already handled.

Next steps

Events: every category and type, with the data of each.
Webhook authentication: verify the body before you trust it.
Cash-in and Cash-out: the flows that produce the main events.

Getting started

API basics

Webhooks

The envelope

Reading a notification

Next steps

​The envelope

​Reading a notification

​Next steps

The envelope

Reading a notification

Next steps