Create Webhook - Documentation

Create org webhook

curl --request POST \
  --url https://api.sandbox.trio.com.br/v2/webhooks \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Trio-Version: <trio-version>' \
  --data '
{
  "authentication_method": "url_secret",
  "entity_id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c",
  "event_categories_allowed": [
    {
      "category": "boleto",
      "types": [
        "settled",
        "created"
      ]
    }
  ],
  "notification_secret": "some_notification_secret",
  "notification_url": "https://mynotificationurl.com/endpoint"
}
'

import requests

url = "https://api.sandbox.trio.com.br/v2/webhooks"

payload = {
    "authentication_method": "url_secret",
    "entity_id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c",
    "event_categories_allowed": [
        {
            "category": "boleto",
            "types": ["settled", "created"]
        }
    ],
    "notification_secret": "some_notification_secret",
    "notification_url": "https://mynotificationurl.com/endpoint"
}
headers = {
    "Trio-Version": "<trio-version>",
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Trio-Version': '<trio-version>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    authentication_method: 'url_secret',
    entity_id: '019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c',
    event_categories_allowed: [{category: 'boleto', types: ['settled', 'created']}],
    notification_secret: 'some_notification_secret',
    notification_url: 'https://mynotificationurl.com/endpoint'
  })
};

fetch('https://api.sandbox.trio.com.br/v2/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.trio.com.br/v2/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'authentication_method' => 'url_secret',
    'entity_id' => '019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c',
    'event_categories_allowed' => [
        [
                'category' => 'boleto',
                'types' => [
                                'settled',
                                'created'
                ]
        ]
    ],
    'notification_secret' => 'some_notification_secret',
    'notification_url' => 'https://mynotificationurl.com/endpoint'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json",
    "Trio-Version: <trio-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.trio.com.br/v2/webhooks"

	payload := strings.NewReader("{\n  \"authentication_method\": \"url_secret\",\n  \"entity_id\": \"019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c\",\n  \"event_categories_allowed\": [\n    {\n      \"category\": \"boleto\",\n      \"types\": [\n        \"settled\",\n        \"created\"\n      ]\n    }\n  ],\n  \"notification_secret\": \"some_notification_secret\",\n  \"notification_url\": \"https://mynotificationurl.com/endpoint\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Trio-Version", "<trio-version>")
	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.trio.com.br/v2/webhooks")
  .header("Trio-Version", "<trio-version>")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"authentication_method\": \"url_secret\",\n  \"entity_id\": \"019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c\",\n  \"event_categories_allowed\": [\n    {\n      \"category\": \"boleto\",\n      \"types\": [\n        \"settled\",\n        \"created\"\n      ]\n    }\n  ],\n  \"notification_secret\": \"some_notification_secret\",\n  \"notification_url\": \"https://mynotificationurl.com/endpoint\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.trio.com.br/v2/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Trio-Version"] = '<trio-version>'
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"authentication_method\": \"url_secret\",\n  \"entity_id\": \"019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c\",\n  \"event_categories_allowed\": [\n    {\n      \"category\": \"boleto\",\n      \"types\": [\n        \"settled\",\n        \"created\"\n      ]\n    }\n  ],\n  \"notification_secret\": \"some_notification_secret\",\n  \"notification_url\": \"https://mynotificationurl.com/endpoint\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "api_version": "v100",
    "authentication_method": "url_secret",
    "entity_id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c",
    "event_categories_allowed": [
      {
        "category": "boleto",
        "types": [
          "settled",
          "created"
        ]
      }
    ],
    "group_id": null,
    "id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7b",
    "inserted_at": "2026-10-01T12:00:00.000000Z",
    "notification_key": "KXe1JxmdHIcRhAsnbaTBvSGNSQli4I798oGMb8abeMBcKzJoUpWkOQ==",
    "notification_secret": "some_notification_secret",
    "notification_url": "https://mynotificationurl.com/endpoint",
    "updated_at": "2026-10-01T12:00:00.000000Z"
  }
}

{
  "error": {
    "error_code": "INVALID_PARAMETER",
    "error_message": "Invalid parameters: /amount: Invalid integer. Got: string",
    "errors": [
      {
        "field": "/amount",
        "message": "Invalid integer. Got: string"
      }
    ]
  }
}

{
  "error": {
    "error_code": "INVALID_PARAMETER",
    "error_message": "Invalid parameters: /amount: Invalid integer. Got: string",
    "errors": [
      {
        "field": "/amount",
        "message": "Invalid integer. Got: string"
      }
    ]
  }
}

{
  "error": {
    "error_code": "INVALID_PARAMETER",
    "error_message": "Invalid parameters: /amount: Invalid integer. Got: string",
    "errors": [
      {
        "field": "/amount",
        "message": "Invalid integer. Got: string"
      }
    ]
  }
}

{
  "error": {
    "error_code": "INVALID_PARAMETER",
    "error_message": "Invalid parameters: /amount: Invalid integer. Got: string",
    "errors": [
      {
        "field": "/amount",
        "message": "Invalid integer. Got: string"
      }
    ]
  }
}

{
  "error": {
    "error_code": "INVALID_PARAMETER",
    "error_message": "Invalid parameters: /amount: Invalid integer. Got: string",
    "errors": [
      {
        "field": "/amount",
        "message": "Invalid integer. Got: string"
      }
    ]
  }
}

POST

webhooks

Create org webhook

curl --request POST \
  --url https://api.sandbox.trio.com.br/v2/webhooks \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Trio-Version: <trio-version>' \
  --data '
{
  "authentication_method": "url_secret",
  "entity_id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c",
  "event_categories_allowed": [
    {
      "category": "boleto",
      "types": [
        "settled",
        "created"
      ]
    }
  ],
  "notification_secret": "some_notification_secret",
  "notification_url": "https://mynotificationurl.com/endpoint"
}
'

import requests

url = "https://api.sandbox.trio.com.br/v2/webhooks"

payload = {
    "authentication_method": "url_secret",
    "entity_id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c",
    "event_categories_allowed": [
        {
            "category": "boleto",
            "types": ["settled", "created"]
        }
    ],
    "notification_secret": "some_notification_secret",
    "notification_url": "https://mynotificationurl.com/endpoint"
}
headers = {
    "Trio-Version": "<trio-version>",
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Trio-Version': '<trio-version>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    authentication_method: 'url_secret',
    entity_id: '019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c',
    event_categories_allowed: [{category: 'boleto', types: ['settled', 'created']}],
    notification_secret: 'some_notification_secret',
    notification_url: 'https://mynotificationurl.com/endpoint'
  })
};

fetch('https://api.sandbox.trio.com.br/v2/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.trio.com.br/v2/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'authentication_method' => 'url_secret',
    'entity_id' => '019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c',
    'event_categories_allowed' => [
        [
                'category' => 'boleto',
                'types' => [
                                'settled',
                                'created'
                ]
        ]
    ],
    'notification_secret' => 'some_notification_secret',
    'notification_url' => 'https://mynotificationurl.com/endpoint'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json",
    "Trio-Version: <trio-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.trio.com.br/v2/webhooks"

	payload := strings.NewReader("{\n  \"authentication_method\": \"url_secret\",\n  \"entity_id\": \"019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c\",\n  \"event_categories_allowed\": [\n    {\n      \"category\": \"boleto\",\n      \"types\": [\n        \"settled\",\n        \"created\"\n      ]\n    }\n  ],\n  \"notification_secret\": \"some_notification_secret\",\n  \"notification_url\": \"https://mynotificationurl.com/endpoint\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Trio-Version", "<trio-version>")
	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.trio.com.br/v2/webhooks")
  .header("Trio-Version", "<trio-version>")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"authentication_method\": \"url_secret\",\n  \"entity_id\": \"019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c\",\n  \"event_categories_allowed\": [\n    {\n      \"category\": \"boleto\",\n      \"types\": [\n        \"settled\",\n        \"created\"\n      ]\n    }\n  ],\n  \"notification_secret\": \"some_notification_secret\",\n  \"notification_url\": \"https://mynotificationurl.com/endpoint\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.trio.com.br/v2/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Trio-Version"] = '<trio-version>'
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"authentication_method\": \"url_secret\",\n  \"entity_id\": \"019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c\",\n  \"event_categories_allowed\": [\n    {\n      \"category\": \"boleto\",\n      \"types\": [\n        \"settled\",\n        \"created\"\n      ]\n    }\n  ],\n  \"notification_secret\": \"some_notification_secret\",\n  \"notification_url\": \"https://mynotificationurl.com/endpoint\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "api_version": "v100",
    "authentication_method": "url_secret",
    "entity_id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c",
    "event_categories_allowed": [
      {
        "category": "boleto",
        "types": [
          "settled",
          "created"
        ]
      }
    ],
    "group_id": null,
    "id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7b",
    "inserted_at": "2026-10-01T12:00:00.000000Z",
    "notification_key": "KXe1JxmdHIcRhAsnbaTBvSGNSQli4I798oGMb8abeMBcKzJoUpWkOQ==",
    "notification_secret": "some_notification_secret",
    "notification_url": "https://mynotificationurl.com/endpoint",
    "updated_at": "2026-10-01T12:00:00.000000Z"
  }
}

{
  "error": {
    "error_code": "INVALID_PARAMETER",
    "error_message": "Invalid parameters: /amount: Invalid integer. Got: string",
    "errors": [
      {
        "field": "/amount",
        "message": "Invalid integer. Got: string"
      }
    ]
  }
}

{
  "error": {
    "error_code": "INVALID_PARAMETER",
    "error_message": "Invalid parameters: /amount: Invalid integer. Got: string",
    "errors": [
      {
        "field": "/amount",
        "message": "Invalid integer. Got: string"
      }
    ]
  }
}

{
  "error": {
    "error_code": "INVALID_PARAMETER",
    "error_message": "Invalid parameters: /amount: Invalid integer. Got: string",
    "errors": [
      {
        "field": "/amount",
        "message": "Invalid integer. Got: string"
      }
    ]
  }
}

{
  "error": {
    "error_code": "INVALID_PARAMETER",
    "error_message": "Invalid parameters: /amount: Invalid integer. Got: string",
    "errors": [
      {
        "field": "/amount",
        "message": "Invalid integer. Got: string"
      }
    ]
  }
}

{
  "error": {
    "error_code": "INVALID_PARAMETER",
    "error_message": "Invalid parameters: /amount: Invalid integer. Got: string",
    "errors": [
      {
        "field": "/amount",
        "message": "Invalid integer. Got: string"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Headers

Trio-Version

enum<string>

required

Version of the v2 contract the client is written against. Each breaking change publishes a new version.

Available options:

2026-10-19.v2

Trio-Target-Org-Id

string<uuid>

ID of another org to act on instead of the API key's own org. The key's org must have been granted access to it, and the request is refused with 403 FORBIDDEN otherwise. When that access or the API key is read-only, only GET and HEAD requests may carry it. When the target org requires mTLS, so does the request. Leave it out to act on the key's own org.

Body

application/json

Org webhook parameters

Webhook to create. A url_secret webhook needs notification_url and notification_secret; an oauth webhook needs oauth_client_id, oauth_client_secret, oauth_url and oauth_scope.

authentication_method

enum<string>

required

How Trio authenticates to the notification URL

Available options:

url_secret,

oauth

notification_url

string

required

URL the events are sent to

api_version

enum<string> | null

Version of the event payloads sent to the webhook. Defaults to v100

Available options:

v100,

v200

entity_id

string<uuid> | null

Entity to limit the webhook to

event_categories_allowed

object[] | null

Events to send to the webhook. Empty or null sends every event

Show child attributes

group_id

string<uuid> | null

Group of the entity to limit the webhook to

notification_secret

string | null

Secret sent with every event, for url_secret webhooks

oauth_client_id

string | null

OAuth client ID

oauth_client_secret

string | null

OAuth client secret

oauth_scope

string | null

OAuth scope

oauth_url

string | null

OAuth token URL

Response

Created webhook

A webhook the org receives its events at

data

V2 Org webhook · object

A webhook the org receives its events at

Show child attributes

Example:

{
  "api_version": "v100",
  "authentication_method": "url_secret",
  "entity_id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c",
  "event_categories_allowed": [
    {
      "category": "boleto",
      "types": ["settled", "created"]
    }
  ],
  "group_id": null,
  "id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7b",
  "inserted_at": "2026-10-01T12:00:00.000000Z",
  "notification_key": "KXe1JxmdHIcRhAsnbaTBvSGNSQli4I798oGMb8abeMBcKzJoUpWkOQ==",
  "notification_secret": "some_notification_secret",
  "notification_url": "https://mynotificationurl.com/endpoint",
  "updated_at": "2026-10-01T12:00:00.000000Z"
}