Events and webhooks - trdrs Engine API

Most of the partner API answers questions you ask. Webhooks are the other direction: trdrs calls your back office when something happens, so you stop polling for it. Register an endpoint, and we POST a signed JSON body to it every time one of your firm’s events fires. You can register up to five endpoints per firm, each with its own event filter, so a billing system and an ops dashboard can subscribe to different things.

What you receive

Every delivery is a POST with the same envelope:

{
  "type": "registration.linked",
  "createdAt": "2026-08-24T19:04:12.318Z",
  "data": {
    "registrationId": "reg_7f3ka9",
    "email": "trader@example.com",
    "accountNumber": "PA-4821-07"
  }
}

The events available today:

Event	Fires when
`registration.linked`	A trader signed in and linked an account your firm registered.
`registration.revoked`	Your firm revoked a pending registration.
`account.reset`	An evaluation account your firm issued was reset.
`balance.recorded`	A credit, debit, or adjustment landed on one of your accounts.
`risk.locked`	Trading was locked on one of your accounts: a risk breach, an evaluation breach, or your own halt.
`risk.unlocked`	That lock cleared.

An endpoint registered with an empty event list receives all of them, including events added later. Name the events explicitly if you would rather opt in deliberately.

Verifying the signature

Every delivery carries a trdrs-signature header:

trdrs-signature: t=1787598252,v1=3f9a1c...64 hex characters

v1 is an HMAC-SHA256, keyed with your endpoint’s signing secret, over the string <t>.<raw request body>. The timestamp is inside the signed material, so a captured body cannot be replayed under a fresh clock. Verify against the raw bytes you received. Parsing the JSON and re-serializing it will change the whitespace and the signature will not match.

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

function verify(secret: string, header: string, rawBody: string): boolean {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header)
  if (!m) return false
  const t = Number(m[1])
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > 300) return false // 5-minute freshness window
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest()
  const given = Buffer.from(m[2]!, 'hex')
  return expected.length === given.length && timingSafeEqual(expected, given)
}

The signing secret is returned when you create the endpoint and on every later read of it, because it authenticates us to your endpoint and grants no access here. Store it with your other secrets all the same.

Retries, and what your handler owes us

Answer 2xx and the delivery is done. Anything else, including a timeout, is a failure and we try again: after 1 minute, 5 minutes, 30 minutes, 2 hours, and 6 hours. That is six attempts across roughly nine hours, which carries a receiver through a deploy or a short outage. After the last attempt the delivery is marked failed and stays in the delivery log for you to read. Two consequences worth designing for: Answer fast, work later. We wait five seconds for a response. Acknowledge the delivery, then do your processing on your own time. A handler that does its work before responding will time out and be retried even though it succeeded. Handle duplicates. Because a timeout is indistinguishable from a failure, a retry can deliver an event your handler already processed. Every payload carries a natural key for this: referenceId on balance and reset events, registrationId on registration events, accountNumber on risk events. Key your processing on those rather than assuming each delivery is new. We refuse to dial private or reserved addresses, and we do not follow redirects. Point the endpoint at its real public URL.

When something is not arriving

POST /api/partner/webhooks/test sends a signed ping to one of your endpoints immediately and reports exactly what your server answered, which separates “our delivery is broken” from “your handler rejected it.” GET /api/partner/webhooks/deliveries is the log: every delivery for an endpoint, newest first, with its status, attempt count, the HTTP status your server returned, and the last error. Terminal deliveries are kept for 60 days. A delivery still pending retry is never aged out. The live routes are in API Reference under Webhooks.

​What you receive

​Verifying the signature

​Retries, and what your handler owes us

​When something is not arriving

What you receive

Verifying the signature

Retries, and what your handler owes us

When something is not arriving