Webhooks

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 for verification and delivery behavior.

Authentication · Errors · Amounts and 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

Request example

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

{
  "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"
  }
}

For failed requests, inspect error.code, error.message and the request ID. Error handling.

List webhook endpoints (secrets masked)

GET /webhooks

Access: partner:read.

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

Request example

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

Response · 200

{
  "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"
    }
  ]
}

For failed requests, inspect error.code, error.message and the request ID. Error handling.

Supported webhook event types

GET /webhooks/events

Access: partner:read.

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

Request example

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

Response · 200

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

For failed requests, inspect error.code, error.message and the request ID. Error handling.

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

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

Response · 200

{
  "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
    }
  ]
}

For failed requests, inspect error.code, error.message and the request ID. Error handling.

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

Request example

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

{
  "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"
  }
}

For failed requests, inspect error.code, error.message and the request ID. Error handling.

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

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

Response · 200

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

For failed requests, inspect error.code, error.message and the request ID. Error handling.

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

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

Response · 201

{
  "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
  }
}

For failed requests, inspect error.code, error.message and the request ID. Error handling.