> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing subscriptions

> Create, update, and manage webhook subscriptions using the Tesouro Notifications API.

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](/embedded-banking/guides/authentication/overview))
* 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Create a subscription">
    ```bash lines theme={null}
    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`:

    ```json lines theme={null}
    {
      "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"
    }
    ```
  </Step>

  <Step title="Verify your subscription">
    ```bash lines theme={null}
    curl https://api.tesouro.com/api/v1/notifications/subscriptions \
      -H "Authorization: Bearer <your-token>"
    ```

    Confirm your subscription appears in the response with `"isActive": true`.
  </Step>
</Steps>

## Managing subscriptions

### List subscriptions

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

```json lines theme={null}
{
  "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

```bash lines theme={null}
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:

```bash lines theme={null}
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

```bash lines theme={null}
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
  }'
```

<Info>
  Inactive subscriptions can't be updated. To reactivate, set `"isActive": true` first, then
  apply further changes.
</Info>

## 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](/embedded-banking/guides/webhooks/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](https://www.rfc-editor.org/rfc/rfc7807) format:

```json lines theme={null}
{
  "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. |