Receive signed events

Webhooks let your backend receive event notifications at a registered endpoint. Use them to trigger processing, then read the relevant API resource when you need its current state.

Register the endpoint

curl --fail-with-body -X POST "$THESAUROS_API_BASE/webhooks" \
  -H "Authorization: Bearer $THESAUROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.example/webhooks/thesauros","events":["position.active","position.withdrawn"]}'

Replace the URL with your receiving endpoint. Save the returned signing secret immediately: list and update responses mask it. The Partner API requires a partner-bound key for webhook operations.

The current event catalogue contains position.opened, position.active, position.rebalanced, position.withdrawn, position.closed, yield.threshold and system.status. Read GET /webhooks/events for the catalogue. Actual emission depends on the connected workflow; registering an event type does not create a settlement integration.

Verify before processing

The delivery carries a Webhook-Signature header with t and v1 components. Verification uses HMAC-SHA256 over the timestamp, a period and the exact raw request body.

signed message = timestamp + "." + raw request body
signature = HMAC-SHA256(signing secret, signed message)

Use the SDK verification helper with the unmodified body. Parsing JSON and then serializing it again can change the signed bytes. Check the timestamp tolerance and signature before processing the event.

Handle the event as a notification

Persist the event ID and make your processing safe to repeat. A delivery can arrive after a newer read of the same resource; use the resource state and your processing history to decide what changes to apply.

The current Partner API makes one delivery attempt per dispatch and records success or failure. It does not implement a durable automatic retry queue. Plan a recovery process using delivery records and API reconciliation rather than relying on automatic redelivery.

Inspect and test delivery

POST /webhooks/{id}/test sends a signed test event to the registered URL. This makes a real HTTP request even when the event is synthetic. Use your own test receiver.

GET /webhooks/deliveries returns recent attempts; the implementation retains up to 500 delivery records per partner. /webhooks/events returns event types in the Partner API, while the sandbox uses that path for a delivery log. Choose the matching contract and SDK client.

Endpoint registration rejects restricted network destinations. Your test receiver must be reachable through an allowed URL.