# Webhooks

Register endpoints, manage subscriptions and inspect delivery attempts.

`GET /webhooks/events` lists event types in this API. Read attempts at `/webhooks/deliveries`. Test delivery sends an HTTP request to the registered receiver. See [webhook implementation](/build/webhooks/) for verification and delivery behavior.

[Authentication](/build/authentication/) · [Errors](/build/errors/) · [Amounts and units](/build/units/)


Response examples below come from a local test account. IDs, balances and timestamps are sample data. Replace IDs and credentials with values from your account.


## Register a webhook endpoint

`POST /webhooks`


The signing secret is returned in full exactly once, at creation.


**Access:** `partner:read`.


**SDK methods:** TypeScript `client.webhooks.create(…)`; Python `client.webhooks.create(…)`.



### Request body

Schema: [CreateWebhookInputDto](/api/partner-models/#createwebhookinputdto)


### Request example

```bash
curl --fail-with-body -X POST "$THESAUROS_API_BASE/webhooks" \
  -H "Authorization: Bearer $THESAUROS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.com/thesauros-webhook","events":["system.status"]}'
```

### Response · 201

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [WebhookEndpoint](/api/partner-models/#webhookendpoint) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "webhook",
  "data": {
    "id": "wh_3925a6b8f0b73ec6",
    "object": "webhook",
    "partner_id": "ptn_seed_acme",
    "url": "https://example.com/thesauros-webhook",
    "events": [
      "system.status"
    ],
    "secret": "REDACTED_EXAMPLE",
    "active": true,
    "created_at": "2026-09-07T14:42:46.343Z"
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## List webhook endpoints (secrets masked)

`GET /webhooks`


**Access:** `partner:read`.


**SDK methods:** TypeScript `client.webhooks.list(…)`; Python `client.webhooks.list(…)`.


### Request example

```bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/webhooks" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [WebhookEndpoint](/api/partner-models/#webhookendpoint)[] | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "list",
  "data": [
    {
      "id": "wh_3925a6b8f0b73ec6",
      "object": "webhook",
      "partner_id": "ptn_seed_acme",
      "url": "https://example.com/thesauros-webhook",
      "events": [
        "system.status"
      ],
      "secret": "REDACTED_EXAMPLE",
      "active": true,
      "created_at": "2026-09-07T14:42:46.343Z"
    }
  ]
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Supported webhook event types

`GET /webhooks/events`


**Access:** `partner:read`.


**SDK methods:** TypeScript `client.webhooks.eventTypes(…)`; Python `client.webhooks.event_types(…)`.


### Request example

```bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/webhooks/events" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [WebhookEventTypes](/api/partner-models/#webhookeventtypes) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "webhook_events",
  "data": {
    "object": "webhook_events",
    "events": [
      "position.opened",
      "position.active",
      "position.rebalanced",
      "position.withdrawn",
      "position.closed",
      "yield.threshold",
      "system.status"
    ]
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Recent delivery attempts, newest first

`GET /webhooks/deliveries`


**Access:** `partner:read`.


**SDK methods:** TypeScript `client.webhooks.deliveries(…)`; Python `client.webhooks.deliveries(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `webhook_id` | query | `string` | No |  |

| `limit` | query | `string` | No |  |

### Request example

```bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/webhooks/deliveries" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [WebhookDelivery](/api/partner-models/#webhookdelivery)[] | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "list",
  "data": [
    {
      "id": "del_f550e6d8562295fc",
      "object": "delivery",
      "webhook_id": "wh_3925a6b8f0b73ec6",
      "partner_id": "ptn_seed_acme",
      "url": "https://example.com/thesauros-webhook",
      "event": "system.status",
      "payload": {
        "id": "evt_75f568c69e76c055",
        "type": "system.status",
        "created_at": "2026-09-07T14:42:46.615Z",
        "data": {
          "message": "Test delivery from the Thesauros Partner API.",
          "requested_at": "2026-09-07T14:42:46.614Z"
        }
      },
      "signature": "REDACTED_EXAMPLE",
      "status": "delivered",
      "attempts": 1,
      "at": "2026-09-07T14:42:46.616Z",
      "latency_ms": 0
    }
  ]
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Update a webhook endpoint

`PATCH /webhooks/{id}`


**Access:** `partner:read`.


**SDK methods:** TypeScript `client.webhooks.update(…)`; Python `client.webhooks.update(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes |  |


### Request body

Schema: [UpdateWebhookInputDto](/api/partner-models/#updatewebhookinputdto)


### Request example

```bash
curl --fail-with-body -X PATCH "$THESAUROS_API_BASE/webhooks/wh_3925a6b8f0b73ec6" \
  -H "Authorization: Bearer $THESAUROS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"active":false}'
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [WebhookEndpoint](/api/partner-models/#webhookendpoint) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "webhook",
  "data": {
    "id": "wh_3925a6b8f0b73ec6",
    "object": "webhook",
    "partner_id": "ptn_seed_acme",
    "url": "https://example.com/thesauros-webhook",
    "events": [
      "system.status"
    ],
    "secret": "REDACTED_EXAMPLE",
    "active": false,
    "created_at": "2026-09-07T14:42:46.343Z"
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Delete a webhook endpoint

`DELETE /webhooks/{id}`


**Access:** `partner:read`.


**SDK methods:** TypeScript `client.webhooks.delete(…)`; Python `client.webhooks.delete(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes |  |

### Request example

```bash
curl --fail-with-body -X DELETE "$THESAUROS_API_BASE/webhooks/wh_3925a6b8f0b73ec6" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [DeletedResource](/api/partner-models/#deletedresource) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "object",
  "data": {
    "id": "wh_3925a6b8f0b73ec6",
    "deleted": true
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Send a signed test event to the endpoint and record the delivery

`POST /webhooks/{id}/test`


**Access:** `partner:read`.


**SDK methods:** TypeScript `client.webhooks.test(…)`; Python `client.webhooks.test(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes |  |

### Request example

```bash
curl --fail-with-body -X POST "$THESAUROS_API_BASE/webhooks/wh_3925a6b8f0b73ec6/test" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 201

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [WebhookDelivery](/api/partner-models/#webhookdelivery) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "delivery",
  "data": {
    "id": "del_f550e6d8562295fc",
    "object": "delivery",
    "webhook_id": "wh_3925a6b8f0b73ec6",
    "partner_id": "ptn_seed_acme",
    "url": "https://example.com/thesauros-webhook",
    "event": "system.status",
    "payload": {
      "id": "evt_75f568c69e76c055",
      "type": "system.status",
      "created_at": "2026-09-07T14:42:46.615Z",
      "data": {
        "message": "Test delivery from the Thesauros Partner API.",
        "requested_at": "2026-09-07T14:42:46.614Z"
      }
    },
    "signature": "REDACTED_EXAMPLE",
    "status": "delivered",
    "attempts": 1,
    "at": "2026-09-07T14:42:46.616Z",
    "latency_ms": 0
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).