Partner webhooks

This is the practical companion to the Webhooks reference pages. It covers everything you need to receive, verify, and reliably process DimeTrades webhook deliveries.

The five-minute summary. Register a webhookUrl; DimeTrades POSTs a signed JSON envelope to it whenever an order or trade you’re exposed to changes state. Verify the X-DimeTrades-Signature header with your webhook secret before trusting the body. Return any 2xx quickly — everything else is retried with backoff. Dedupe on the envelope’s id, since a retried delivery reuses it.

1. Setup

Webhook delivery is configured per brand by your DimeTrades account contact:

A webhookUrl is set on your brand — the HTTPS endpoint deliveries are POSTed to.
A signing secret is issued — shown to you exactly once, the same way an API secret is. Store it like any other credential; it cannot be retrieved again, only rotated (which invalidates the old one).
Delivery can be paused at any time without losing the URL/secret configuration.

There is no self-serve registration endpoint yet — deliveries only start once both a URL and a secret are configured on your brand.

2. Verifying a delivery

Every delivery carries three headers on top of the JSON body:

POST /your/webhook/path HTTP/1.1
Content-Type: application/json
X-DimeTrades-Event-Id: 54b1fca5-697c-4b22-937f-e78abb9bb42f
X-DimeTrades-Event-Type: trade.executed
X-DimeTrades-Signature: t=1786384403,v1=6ac323d7d75b7e9f6cbfce6acc19edc657798f1e30dcd00c933cba5a4000a58b

X-DimeTrades-Signature is t=<unix seconds>,v1=<hex signature>, where:

v1 = HMAC-SHA256(webhookSecret, "{t}.{rawRequestBody}")

To verify (pseudocode, Stripe-style):

const [tPart, vPart] = req.headers["x-dimetrades-signature"].split(",");
const t = tPart.split("=")[1];
const v1 = vPart.split("=")[1];

const expected = hmacSha256Hex(webhookSecret, `${t}.${rawBody}`);
if (!timingSafeEqual(expected, v1)) throw new Error("bad signature");

const age = Date.now() / 1000 - Number(t);
if (age > 300) throw new Error("stale delivery — possible replay");

Compute the signature over the raw request body bytes, before any JSON parsing or re-serialization — re-stringifying a parsed object can reorder keys or change whitespace and will not match.

Use a constant-time comparison for the signature check (timingSafeEqual or equivalent), not === — a naive string comparison leaks timing information an attacker can use to forge a valid signature byte by byte.

3. Retries & idempotency

If your endpoint doesn’t return a 2xx status (including on a timeout), delivery is retried with exponential backoff:

Attempt	Delay before this attempt
1	immediate
2	30s
3	2m
4	10m
5	1h
6–8	6h (repeats)
after 8	given up — no further retries

Every retry of the same logical event reuses the same id. Process deliveries idempotently — key any side effects (e.g. updating your own order ledger) off id, not off receipt time, so a retried delivery after a slow 2xx you never saw doesn’t double-apply.

Delivery is at-least-once, never exactly-once, and order between different events is not guaranteed if your endpoint is slow enough for retries to interleave. Treat each event’s data as the authoritative state at that point in time — don’t assume you’ll never see order.filled before a order.partially_filled you’re still retrying.

4. Responding fast

Acknowledge receipt (2xx) as soon as you’ve durably queued the event — before doing any slow downstream work (calling your own services, writing to your database beyond an initial “received” marker). A slow 2xx still counts as a timeout from our side and triggers a redundant retry.

5. Event catalog

Event	Fires when
`order.accepted`	An order is accepted into the order book (once, not on redelivery)
`order.partially_filled`	An order receives a partial fill
`order.filled`	An order is fully filled
`order.cancelled`	An order is cancelled (user, admin, system, or self-trade prevention)
`order.rejected`	The matching engine rejects an order before any matching
`order.modified`	A resting order’s price and/or quantity changes
`order.modify_rejected`	A modify request is rejected — the order is unchanged
`order.cancel_rejected`	A cancel request is rejected — nothing to cancel
`order.expired`	A GTT order reaches its expiry unfilled
`trade.executed`	A fill happens — delivered once per side (twice if both sides are your customers)
`trade.busted`	An admin busts a trade — once per player of yours in it, with `resolution` (`reversed` or `corrected_to_fair_value`). Your own order and trade data only
`trade.corrected`	An admin re-prices a trade — once per player of yours, with the signed `adjustmentCents` and the old and new price on their contract side
`market.terminated`	A market is voided. Broadcast to every brand with delivery configured — the market catalog is shared, not brand-owned
`wallet.debit`	A BUY order fills — trade cost + fee to deduct from your customer’s balance, split in `costCents` and `feeCents` (with `quantity`, `priceCents` and `role`)
`wallet.credit`	Money to add to your customer’s balance: SELL proceeds or an auto-merge payout (`reason: settlement`, with the same `costCents`/`feeCents`/`quantity`/`priceCents`/`role` split as the debit), a bust reversal or correction (`trade_bust_reversal`, `trade_bust_correction`), a price correction (`price_correction`), or a market resolving or being refunded (`reason: market_settlement`, one event per settled position). A bust or price correction can also be a `wallet.debit` when the customer owes money

wallet.debit/wallet.credit are only sent to brands with external wallet integration enabled. If you manage your own users’ balances (REQ-01), DimeTrades holds no wallet of its own for them — these two events are the authoritative instruction to apply the debit/credit on your side, not an FYI. Dedupe on id is not optional here the way it’s a good idea for the other events: applying the same one twice double-charges or overpays your customer. They’re documented in full, alongside the synchronous reservation-confirmation check DimeTrades calls on your side (a plain POST endpoint, not a webhook — see Confirm a wallet reservation), in the External wallet integration guide and its own External Wallet Webhooks reference section — not under Webhooks like the rest of this table.

Every wallet.debit/wallet.credit reason and the exact events each money flow sends are listed in the Wallet events reference. Full request/response shapes and one example payload per event are on the Webhooks reference pages, generated from the same OpenAPI spec as the rest of this API.

Busts and price corrections. trade.busted and trade.corrected announce them, and for customers whose cash you hold the matching wallet.credit / wallet.debit carries the money. There is no need to poll trade history. Your endpoint must be subscribed to the new events; see the Wallet events reference.

6. A minimal receiver

import crypto from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const [tPart, vPart] = signatureHeader.split(",");
  const t = tPart.split("=")[1];
  const v1 = vPart.split("=")[1];
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) {
    throw new Error("invalid signature");
  }
  if (Date.now() / 1000 - Number(t) > 300) {
    throw new Error("stale delivery");
  }
}

app.post(
  "/webhooks/dimetrades",
  express.raw({ type: "application/json" }), // keep the raw body for verify()
  (req, res) => {
    verify(req.body, req.headers["x-dimetrades-signature"], process.env.DIMETRADES_WEBHOOK_SECRET);
    const event = JSON.parse(req.body);

    if (await alreadyProcessed(event.id)) return res.sendStatus(200); // idempotency
    await enqueue(event); // durably queue, THEN do slow work async
    res.sendStatus(200);
  }
);

Getting started

Reference

Events & markets

Webhooks

External Wallet

WebSockets

1. Setup

2. Verifying a delivery

3. Retries & idempotency

4. Responding fast

5. Event catalog

6. A minimal receiver

​1. Setup

​2. Verifying a delivery

​3. Retries & idempotency

​4. Responding fast

​5. Event catalog

​6. A minimal receiver

1. Setup

2. Verifying a delivery

3. Retries & idempotency

4. Responding fast

5. Event catalog

6. A minimal receiver