Skip to main content
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": "MBP_MONETARY_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": "MBP_MONETARY_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": "MBP_MONETARY_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

MethodEndpointDescriptionScope
GET/api/v1/notifications/subscriptionsList subscriptionsnotification:subscription:read
POST/api/v1/notifications/subscriptionsCreate a subscriptionnotification:subscription:write
GET/api/v1/notifications/subscriptions/{id}Get a subscriptionnotification:subscription:read
PATCH/api/v1/notifications/subscriptions/{id}Update a subscriptionnotification:subscription:write

​
Create subscription request

FieldTypeRequiredDescription
eventTypestringYesEvent type to subscribe to (see Event types)
channelTypestringYesDelivery channel. Currently: WEBHOOK
channelConfigobjectYesChannel configuration
channelConfig.typestringYesMust be "webhook"
channelConfig.urlstringYesYour webhook endpoint URL

​
Update subscription request

At least one field must be provided.
FieldTypeRequiredDescription
channelTypestringNoNew channel type (requires channelConfig if provided)
channelConfigobjectNoNew channel configuration
isActivebooleanNoActivate or deactivate the subscription

​
Subscription object

FieldTypeDescription
idUUIDUnique subscription identifier
organizationIdUUIDYour organization ID
eventTypestringSubscribed event type
channelTypestringDelivery channel
channelConfig.urlstringYour webhook endpoint
channelConfig.mtlsEnabledbooleanWhether mTLS is enabled
isActivebooleanSubscription status
createdAtdatetimeCreation timestamp (UTC)
updatedAtdatetimeLast 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"
}
StatusMeaning
400Invalid request: missing fields, invalid URL, or validation failure
401Missing or invalid authentication token
403Valid token but insufficient scopes
404Subscription not found or not owned by your organization
409Duplicate: a subscription with the same event type, channel, and URL already exists. Response body contains the existing subscription.