Receive events on your server

Stop polling for changes. Register an HTTPS endpoint and trdrs sends it a signed JSON message each time one of your events happens: a registration linking, an account resetting, a balance operation recording, an account locking or unlocking, or a hedge moving. Your server verifies the signature, answers 2xx, and does its work. Use this page when you connect your back office, billing or onboarding system to trdrs. By the end you have an endpoint registered, a handler that verifies every delivery, and a way to recover any delivery your handler missed.

Before you start

A Venue key with venue:configure to register, test and remove endpoints, and venue:read to list them and read deliveries.
An HTTPS endpoint reachable on the public internet. trdrs doesn’t deliver to private or reserved addresses and doesn’t follow redirects, so use its real public URL.

The examples use the variables from Run a venue.

Send an https URL of at most 500 characters, and name the events you want in events. Leave events out, or send an empty list, to receive every event type.Required scope: venue:configure.

curl -X POST "$TRDRS_API_BASE_URL/api/venues/$VENUE/webhooks" \
  -H "Authorization: Bearer $TRDRS_VENUE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ops-hook-2026-09-20" \
  -d '{
    "url": "https://ops.yourfirm.example/hooks/trdrs",
    "events": ["registration.linked", "risk.locked", "balance.recorded"]
  }'

const res = await fetch(`${process.env.TRDRS_API_BASE_URL}/api/venues/${process.env.TRDRS_VENUE_ID}/webhooks`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TRDRS_VENUE_KEY}`,
    'content-type': 'application/json',
    'Idempotency-Key': 'ops-hook-2026-09-20',
  },
  body: JSON.stringify({
    url: 'https://ops.yourfirm.example/hooks/trdrs',
    events: ['registration.linked', 'risk.locked', 'balance.recorded'],
  }),
})
const webhook = await res.json()

The response is 201 with the endpoint, its id and its signing secret. The secret is shown again every time you list your endpoints, because all it does is prove a delivery came from trdrs.The Idempotency-Key is required, but it doesn’t deduplicate this write: a retry registers a second endpoint, so list your webhooks before you retry. Your venue holds at most five endpoints, so a billing system and an operations dashboard can each subscribe to different events. The endpoints belong to your venue, so every key and the back office see the same five.

Send a test ping

Send a signed ping to your endpoint right now. It uses the real signature, headers and network path, so it’s the call to run while you build your handler.Required scope: venue:configure.

curl -X POST "$TRDRS_API_BASE_URL/api/venues/$VENUE/webhooks/$WEBHOOK/test" \
  -H "Authorization: Bearer $TRDRS_VENUE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ping-1" \
  -d '{}'

WEBHOOK is the endpoint’s id. The response says what your endpoint answered. If it refused the ping, the call still answers 200, with ok: false, the status your endpoint returned and the reason: the call did its job, and your endpoint’s failure is reported rather than raised. A test ping isn’t retried and doesn’t appear in the delivery log.

Verify every delivery

Each delivery carries a trdrs-signature header of the form t=<epoch seconds>,v1=<64 hex characters>. v1 is an HMAC-SHA256 of the string <t>.<raw request body>, keyed with your endpoint’s signing secret. Check it before you parse the body:

import { createHmac, timingSafeEqual } from 'node:crypto'

// rawBody is the exact bytes received. Verify before JSON.parse, not after.
function verify(secret: string, header: string, rawBody: string): boolean {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header)
  if (!m) return false
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > 300) return false // stale
  const expected = createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest()
  const given = Buffer.from(m[2], 'hex')
  return expected.length === given.length && timingSafeEqual(expected, given)
}

The function returns true only for a genuine, recent delivery. Two rules make it work. The timestamp is part of what’s signed, so reject anything more than five minutes old and a captured message can’t be replayed later. And verify the bytes you received: parsing the JSON and serializing it again changes the whitespace, and the signature won’t match.

Answer quickly, and expect repeats

Answer 2xx to accept a delivery. trdrs waits five seconds for your answer, so acknowledge first and do the work afterwards; a handler that works before answering times out and is retried even though it succeeded.Anything other than 2xx, including a timeout, is retried on the retry schedule, for about nine hours. That carries your endpoint through a deploy or a short outage, and it means the same event can arrive twice. Key your handler on the event’s own key: referenceId for balance and reset events, registrationId for registration events, eventId for risk events, and targetId or intentId for hedge events.

Read the log when something goes quiet

The delivery log for one endpoint lists, newest first, what trdrs sent, what your endpoint answered, and what’s still waiting.Required scope: venue:read.

curl "$TRDRS_API_BASE_URL/api/venues/$VENUE/webhooks/$WEBHOOK/deliveries?limit=100" \
  -H "Authorization: Bearer $TRDRS_VENUE_KEY"

limit is 1 to 200 and defaults to 50. A value outside that range is refused with 400, never quietly adjusted. Each row carries the exact message sent, so you can replay one your handler dropped.

Read the event catalog

Event	Fires when
`registration.linked`	A trader signed in and linked an account your venue registered.
`registration.revoked`	Your venue revoked a pending registration.
`account.reset`	An account you issued was reset.
`balance.recorded`	A credit, debit or adjustment landed on one of your accounts. `data` carries the account number, the `op`, the amount, the account’s `currency` and your `referenceId`.
`risk.locked`	Trading was locked on one of your accounts: a risk control fired, a stage rule was broken, or you halted it.
`risk.unlocked`	That lock cleared.
`hedge.target`	A hedge calculation saved a target.
`hedge.intent`	A hedge order was prepared, or its state changed.
`hedge.drift`	A hedge calculation found a gap between the target and what the hedge account holds.
`hedge.fill`	A hedge order filled, fully or in part.
`hedge.failure`	A hedge order was refused, or its outcome is unknown.
`hedge.halt`	A hedging emergency stop ran.

Every delivery uses the same envelope: a type, a createdAt, and a data object with the event’s own fields.

{
  "type": "risk.locked",
  "createdAt": "2026-08-24T19:41:07.412Z",
  "data": {
    "accountNumber": "EVAL-7C21A9",
    "reason": "eval_breach",
    "eventId": "5f0c6a1e-2b7d-4c1a-9e3f-7d2a4b8c6e10",
    "revision": 3
  }
}

Risk events need one extra rule, because a retried delivery can arrive after a later one:

eventId names the lock change. Every delivery of it, to each endpoint and on every retry, carries the same value.
revision counts the account’s lock changes. Apply a risk event only when its revision is higher than the last one you applied for that account, and read what the account may do when you need the current answer.
reason names what locked the account, and is null on risk.unlocked.

A risk event is recorded in the same transaction as the lock change, so a restart can’t lose one. It goes to the endpoints subscribed to it when it’s queued, normally within seconds of the change. An account that was already locked when you issued it produces no risk.locked for that lock.

Read a delivery row

Field	What it tells you
`status`	`delivered` is done. `pending` is still being retried. `failed` means the retries ran out.
`attempts`	How many times trdrs has tried.
`responseStatus`	The HTTP status your endpoint returned, or `null` when the connection never completed.
`lastError`	Why the latest attempt failed.
`createdAt`, `lastAttemptAt`	When the event happened, and when trdrs last tried.
`payload`	The exact JSON sent, or about to be sent.

Finished rows are kept for 60 days. A row still being retried is never removed.

Remove an endpoint

Removing an endpoint stops deliveries to it at once and deletes its delivery log, so read anything you still need first. Removing one endpoint never affects another. The call takes no body and no Idempotency-Key. Required scope: venue:configure.

curl -X DELETE "$TRDRS_API_BASE_URL/api/venues/$VENUE/webhooks/$WEBHOOK" \
  -H "Authorization: Bearer $TRDRS_VENUE_KEY"

The response is { "id": "...", "deleted": true }.

Follow the retry schedule

Attempt	After the previous one
1	Immediately
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	6 hours

That’s six attempts over about nine hours, with five seconds allowed for each.

Handle errors

Status and code	When	What to do
`400` with `field: "url"`	The URL isn’t `https`, doesn’t parse, or is longer than 500 characters.	Use the endpoint’s public HTTPS URL.
`400 unknown_event_type`	An event isn’t in the catalog. The error lists the valid ones.	Fix the name.
`409 webhook_limit`	You already have five endpoints.	Remove one first.
`404`	No endpoint with that id belongs to your venue.	List your endpoints.

Test it end to end

Register an endpoint for every event and send it a test ping. Your handler verifies the signature and answers 2xx.
In the sandbox, credit a test account with a new Idempotency-Key. Your endpoint receives balance.recorded with that key as referenceId.
Halt the account, then resume it. Your endpoint receives risk.locked and then risk.unlocked with a higher revision.
Stop your endpoint, credit the account again, and read the delivery log: the delivery is pending. Start your endpoint and it arrives on the next retry.

Start here

Set up your venue

Run accounts

Connect pre-registration

Check your integration

Receive events on your server

Before you start

Read the event catalog

Read a delivery row

Remove an endpoint

Follow the retry schedule

Handle errors

Test it end to end

Next steps

Follow registrations

Venue accounts

​Before you start

​Read the event catalog

​Read a delivery row

​Remove an endpoint

​Follow the retry schedule

​Handle errors

​Test it end to end

​Next steps

Follow registrations

Venue accounts

Before you start

Read the event catalog

Read a delivery row

Remove an endpoint

Follow the retry schedule

Handle errors

Test it end to end

Next steps