Follow registrations

Know the moment a trader links an account you registered. A registration stays pending until the trader acts, and two webhook events tell your server what happened: registration.linked and registration.revoked. This page covers those two events. The endpoint, the signature check, the retries and the delivery log work the same for every event and live in Receive events, so set that up first. By the end your onboarding system marks a registration complete as soon as the trader links it, and catches any delivery it missed.

Subscribe to the two registration events

Register an endpoint that receives only the onboarding events, so your onboarding system gets nothing else. Leaving events out, or sending an empty list, receives 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: onboarding-hook-1" \
  -d '{
    "url": "https://ops.yourfirm.example/hooks/trdrs-onboarding",
    "events": ["registration.linked", "registration.revoked"]
  }'

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': 'onboarding-hook-1',
  },
  body: JSON.stringify({
    url: 'https://ops.yourfirm.example/hooks/trdrs-onboarding',
    events: ['registration.linked', 'registration.revoked'],
  }),
})
const webhook = await res.json()

The response is 201 with the endpoint and its signing secret. You can have five endpoints, so an onboarding system and a billing system can each keep their own filter.

Registration events go to the endpoints of the venue your pre-registration key acts for. A Venue key registers endpoints on its own venue, so the call above receives them when your pre-registration key and your Venue key act for the same venue.

Read the payload

Every delivery is a POST with the same envelope: a type, a createdAt, and a data object. For a linked registration, data carries the registration’s id, the trader’s email and the account number, the things you sent when you created it, so you can find your own record without a lookup table. A cancelled registration’s data carries its id.

{
  "type": "registration.linked",
  "createdAt": "2026-08-24T19:04:12.318Z",
  "data": {
    "registrationId": "3f9c2b1e-8a4d-4c6b-9e2f-1a7d5c0b8e34",
    "email": "trader@example.com",
    "accountNumber": "PA-4821-07"
  }
}

Event	Fires when	What to do
`registration.linked`	A trader signed in and linked an account you registered.	Mark the registration complete. The account trades from now on, and can count toward your usage.
`registration.revoked`	You cancelled a pending registration.	Treat it as confirmation of the cancellation your own system asked for.

No event fires when a registration expires. A pending registration that nobody links passes its expiresAt quietly, so you notice expiry on the list.

Handle a delivery twice without harm

A delivery your endpoint doesn’t answer with 2xx, including one that times out, is retried for about nine hours, so the same event can arrive more than once. Key your processing on registrationId in the payload, which stays the same across retries.

Reconcile against the list

The registration list is the settling read: it’s built from the same records the events come from.Read it on a schedule and compare it with your own table. A registration your table calls pending but the list calls linked is a delivery you missed. One the list calls expired is a trader who never arrived.

Resolve a mismatch with our records

Work down this list. Each step is cheaper than the next.

The registration list. It’s the source of truth for status. If it says linked, the trader linked the account, whatever your table says.
The delivery log. GET /api/venues/{venueId}/webhooks/{webhookId}/deliveries lists every attempt for one endpoint, newest first, each with the exact payload sent, so you can replay an event your endpoint dropped. pending means it’s still being retried; failed means the retries ran out.
A test ping. POST /api/venues/{venueId}/webhooks/{webhookId}/test sends a signed ping right now and reports exactly what your endpoint answered. It tells a broken delivery apart from a handler that’s refusing.

Finished delivery rows are kept for 60 days; a row still being retried is never removed. Deleting an endpoint deletes its delivery log too, so read what you need first.

Test it end to end

Register a test endpoint for the two events and send it a test ping. Your endpoint verifies the signature and answers 2xx.
Register an account for a sandbox test trader, then cancel it. Your endpoint receives registration.revoked with that registrationId.
Register it again and link it by signing in as the test trader. Your endpoint receives registration.linked.

Start here

Set up your venue

Run accounts

Connect pre-registration

Check your integration

Resolve a mismatch with our records

Test it end to end

Next steps

Receive events

Register an account

​Resolve a mismatch with our records

​Test it end to end

​Next steps

Receive events

Register an account

Resolve a mismatch with our records

Test it end to end

Next steps