Managing subscriptions - Tesouro

Webhook subscriptions are managed through the Tesouro Notifications API. Each subscription maps an event type to your webhook endpoint. Base URL: https://api.tesouro.com/api/v1/notifications/subscriptions

Prerequisites

Before creating a subscription:

A valid authentication token (see Authentication)
A publicly accessible HTTPS endpoint that accepts POST requests and returns a 2xx status code
The following authorization scopes:
- notification:subscription:read: list and view subscriptions
- notification:subscription:write: create and update subscriptions

Quick start

1

Set up your webhook endpoint

Your endpoint must:

Accept HTTP POST requests
Return a 2xx status code to acknowledge receipt
Be publicly accessible over HTTPS

Process payloads asynchronously. Return 200 OK immediately and queue the work.

2

Create a subscription

curl -X POST https://api.tesouro.com/api/v1/notifications/subscriptions \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "LEDGER_TRANSACTION",
    "channelType": "WEBHOOK",
    "channelConfig": {
      "type": "webhook",
      "url": "https://your-domain.com/webhooks/tesouro"
    }
  }'

A successful response returns 201 Created:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organizationId": "org-uuid",
  "eventType": "LEDGER_TRANSACTION",
  "channelType": "WEBHOOK",
  "channelConfig": {
    "url": "https://your-domain.com/webhooks/tesouro",
    "mtlsEnabled": false
  },
  "isActive": true,
  "createdAt": "2026-04-07T12:00:00Z",
  "updatedAt": "2026-04-07T12:00:00Z"
}

3

Verify your subscription

curl https://api.tesouro.com/api/v1/notifications/subscriptions \
  -H "Authorization: Bearer <your-token>"

Confirm your subscription appears in the response with "isActive": true.

Managing subscriptions

List subscriptions

curl "https://api.tesouro.com/api/v1/notifications/subscriptions?page=1&pageSize=10" \
  -H "Authorization: Bearer <your-token>"

{
  "subscriptions": [
    {
      "id": "a3f1c2d4-5e6b-7890-abcd-ef1234567890",
      "organizationId": "b7e2d1f3-4c5a-6789-bcde-f01234567891",
      "eventType": "LEDGER_TRANSACTION",
      "channelType": "WEBHOOK",
      "channelConfig": {
        "type": "webhook",
        "url": "https://your-domain.com/webhooks/notifications"
      },
      "isActive": true,
      "createdAt": "2026-04-13T10:30:00Z",
      "updatedAt": "2026-04-13T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalCount": 2,
    "totalPages": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

Get a subscription

curl https://api.tesouro.com/api/v1/notifications/subscriptions/{id} \
  -H "Authorization: Bearer <your-token>"

Update a subscription

Use PATCH to update the webhook URL:

curl -X PATCH https://api.tesouro.com/api/v1/notifications/subscriptions/{id} \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "channelType": "WEBHOOK",
    "channelConfig": {
      "type": "webhook",
      "url": "https://new-domain.com/webhooks/tesouro"
    }
  }'

Deactivate a subscription

curl -X PATCH https://api.tesouro.com/api/v1/notifications/subscriptions/{id} \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

Inactive subscriptions can’t be updated. To reactivate, set "isActive": true first, then apply further changes.

API reference

Endpoints

Method	Endpoint	Description	Scope
`GET`	`/api/v1/notifications/subscriptions`	List subscriptions	`notification:subscription:read`
`POST`	`/api/v1/notifications/subscriptions`	Create a subscription	`notification:subscription:write`
`GET`	`/api/v1/notifications/subscriptions/{id}`	Get a subscription	`notification:subscription:read`
`PATCH`	`/api/v1/notifications/subscriptions/{id}`	Update a subscription	`notification:subscription:write`

Create subscription request

Field	Type	Required	Description
`eventType`	string	Yes	Event type to subscribe to (see Event types)
`channelType`	string	Yes	Delivery channel. Currently: `WEBHOOK`
`channelConfig`	object	Yes	Channel configuration
`channelConfig.type`	string	Yes	Must be `"webhook"`
`channelConfig.url`	string	Yes	Your webhook endpoint URL

Update subscription request

At least one field must be provided.

Field	Type	Required	Description
`channelType`	string	No	New channel type (requires `channelConfig` if provided)
`channelConfig`	object	No	New channel configuration
`isActive`	boolean	No	Activate or deactivate the subscription

Subscription object

Field	Type	Description
`id`	UUID	Unique subscription identifier
`organizationId`	UUID	Your organization ID
`eventType`	string	Subscribed event type
`channelType`	string	Delivery channel
`channelConfig.url`	string	Your webhook endpoint
`channelConfig.mtlsEnabled`	boolean	Whether mTLS is enabled
`isActive`	boolean	Subscription status
`createdAt`	datetime	Creation timestamp (UTC)
`updatedAt`	datetime	Last update timestamp (UTC)

Error responses

Errors follow the RFC 7807 Problem Details format:

{
  "type": "string",
  "title": "string",
  "status": 400,
  "detail": "Detailed error message",
  "instance": "/api/v1/notifications/subscriptions"
}

Status	Meaning
`400`	Invalid request: missing fields, invalid URL, or validation failure
`401`	Missing or invalid authentication token
`403`	Valid token but insufficient scopes
`404`	Subscription not found or not owned by your organization
`409`	Duplicate: a subscription with the same event type, channel, and URL already exists. Response body contains the existing subscription.

Webhooks Event types

⌘I