Skip to main content
Most operations on Trio are asynchronous: a Pix payment, a boleto or an onboarding is accepted first and settles, fails or is approved later, in the background. A webhook is the URL Trio calls with an HTTP POST and a JSON payload each time one of those events happens, so your system reacts to the final state without polling the API.

​
Register a webhook

You can register a webhook in two ways:
The response is the webhook, with its id and a generated notification_key: the key Trio signs the events with. Store the key; you need it to verify every notification you receive.

​
Choose the payload version

api_version selects the version of the event payloads Trio sends to the webhook. The version belongs to the webhook, not to your API credential, so you can register a second webhook on v200 and compare its payloads with the ones you already handle before switching. Both versions share the same envelope, described in Content and structure. Onboarding events (category entity) have a single format and are sent to webhooks of both versions.

​
Choose which events you receive

By default a webhook receives every event of your organization. Three optional fields narrow it down:
  • event_categories_allowed lists the categories and types you want. For example, { "category": "boleto", "types": ["settled", "created"] } delivers only those two boleto events; "types": [] delivers every type of the category. The types are the ones listed on the Events page. In event_categories_allowed the four document categories still use their V1 names, even for a v200 webhook: write collecting_document for in_document, collecting_document_refund for in_document_refund, payment_document for out_document and payment_document_refund for out_document_refund. The V2 document names are refused with 422 in this field; every other category uses the same name in the filter and in the notification.
  • entity_id limits the webhook to the events of one entity.
  • group_id limits it to the events of one group of that entity.
Today the three filters apply to v100 webhooks and to entity events. A v200 webhook receives every event of the eleven V2 categories of the organization, whatever its event_categories_allowed, entity_id and group_id. Filter on category, type and data.entity_id in your handler until this changes.

​
Delivery and retries

Trio delivers every notification as an HTTP POST with a JSON body to notification_url, with the headers described in Webhook authentication. Your endpoint must accept that method and content type.
  • Acknowledge fast. Trio waits 1 second for the response. A 200, 201, 202 or 204 status marks the notification as delivered.
  • Errors are retried. When your endpoint answers any other status, refuses the connection or fails the TLS handshake, Trio queues the notification for retry. The first retry comes 5 seconds after the failure and the wait doubles at each new failure, up to 3 minutes between attempts. Trio stops after 24 attempts or 1 hour after the first failure, whichever comes first.
  • Timeouts are not retried. A notification your endpoint does not answer within 1 second is logged as a timeout and is not sent again. Read the resource back from the API if you suspect you missed an event.
  • Serve the endpoint over HTTPS so the payload is protected in transit.
Answer with a 2XX as soon as you have stored the notification and do the heavy work afterwards. A retried notification carries the same event again, so keep your processing idempotent: treat ref_id, category and type together as the key of a notification.

​
Manage webhooks

Every webhook of the organization is managed through the API or the Trio App:
  • List webhooks returns every webhook in a single page; the list is not paginated.
  • Get webhook returns one webhook, including its notification_key.
  • Replace webhook replaces a webhook with the one you send. Send every field: an omitted field is cleared, so leaving out entity_id or event_categories_allowed removes that filter.
  • Delete webhook stops the deliveries.

​
Next steps