Webhooks

A queued delivery is a durable row, and it is retried until it is acknowledged or its attempts are used up. An endpoint receives the events raised while it is registered, active and subscribed to that type: an event raised while your endpoint is inactive, or not subscribed to that type, is not queued to it. A newly registered endpoint starts from the moment it is registered. The reconciliation feed holds the full history, so it is how you catch up on anything earlier.

Payloads are narrowed to the partner form exactly as the REST surface is: opaque ctr_… contract ids and no source named anywhere. That now holds where it is decided, at the point an event is recorded, rather than being promised of a delivery step. The dedupeKey is narrowed with the body, because it is published verbatim in the envelope and again on the reconciliation feed.

Every shape below is the object that is actually stored on the event and serialised into data. They are published in the OpenAPI document as well, one schema per event type.

order.filled is keyed on the fill, not the order. An order that fills in pieces raises one event per piece, and dedupeKey is order.filled:<orderId>:<fillId>. operatorMoney is cumulative for the order, never per fill: an amount stamped on each fill is an amount you can debit twice.

{
  "orderId": "3dd27f36-7780-4aa7-8af2-1a6854fbf8cb",
  "executionRef": "Parity_Best_7K2M9QH4TR8DXZ",  // quote this to Parity support
  "clientOrderId": "your-order-id",
  "externalUserId": "your-player-id",
  "fillId": "9b1e4c2a-0f6d-4e38-a5b7-6c2d8e1f3a90",           // this fill. the tail of dedupeKey
  "contractId": "ctr_4919562d19a0f299",
  "side": "YES",
  "action": "buy",
  "fillQuantity": 19,               // THIS fill
  "fillPrice": 0.52,                // THIS fill
  "filledQuantity": 19,             // the ORDER, to date
  "averagePrice": 0.52,             // the ORDER, to date
  "status": "partially_filled",
  "transmissionState": "unknown",   // read this BEFORE releasing anything
  "operatorMoney": {                // cumulative for the ORDER
    "currency": "USD",
    "authorizationAmount": "25.00",
    "actualDebit": "10.00",
    "releaseAmount": "15.00",
    "tradeAmount": "9.88",
    "platformFee": "0.12",
    "venueFee": "0.00",
    "venueFeeKnown": false
  },
  "operatorExitMoney": null,        // the sell leg. null on a buy
  "simulated": false,
  "fillSequence": 1,                // 1 for the first fill, 2 for the second...
  "partial": true,                  // true until known to have filled in full
  "final": false,                   // true once no further fill can arrive
  "fillMoney": {                    // THIS fill only. itemisation, not what you book
    "currency": "USD",
    "tradeAmount": "9.88",
    "platformFee": "0.12",
    "venueFee": "0.00",
    "venueFeeKnown": false,
    "actualDebit": "10.00",         // on a buy. null on a sell
    "sellProceeds": null            // on a sell. null on a buy
  }
}

Every amount is an exact decimal string in major units of its currency ("10.00" is ten dollars), never a JSON number. Quantities and prices stay numbers: they are facts you read, not amounts you book.

Book from operatorMoney, never from fillMoney. For each order, keep what you have already booked and the highest fillSequence you have applied. When an event arrives with a higher fillSequence, book the difference between its operatorMoney.actualDebit (or operatorExitMoney.sellProceeds on a sell) and what you already booked; ignore an event with a lower one, because a retried delivery can arrive after a later fill. This is idempotent and it heals itself: every event carries the order’s full total, so one lost event is made good by the next. Poll GET /api/v1/orders/{id} for the same figures.

fillMoney is itemisation: what this one fill moved, for a statement line or a reconciliation. It is not a booking source. An event can be lost if our process stops between recording a fill and emitting its event, and a fill we have already recorded is never announced twice, so a sum of fillMoney can have a gap that nothing fills in. When no event is missing it adds up to the cumulative block to the cent. The release of any unspent authorization is only ever in operatorMoney.releaseAmount.

fillSequence, partial, final and fillMoney are absent on events created before they were introduced. A retry resends the stored event exactly as it was first written, so treat all four as optional.

partial and final say outright what status and transmissionState imply. final is true exactly when transmissionState is resolved. partial stays true until the order is known to have filled in full, so partial with final is an order that closed short and has a remainder to release. Orders are placed as a cash amount, not a contract count, so what remains unfilled is expressed as money: operatorMoney.releaseAmount.

The push that says the order is finished is order.completed. On an order sent to the market, each fill is recorded while the order is still open, so its order.filled carries partial: true and, in almost every case, final: false. When the venue then closes the order, one order.completed is raised with final: true, the cumulative block as it finally stands and the releaseAmount to hand back. Book the last delta from it and apply the release. Like any event it can be missing, so an order that has taken fills and has not completed is still worth a read of GET /api/v1/orders/{id}: once transmissionState is resolved, apply the release it shows.

{
  "orderId": "3dd27f36-7780-4aa7-8af2-1a6854fbf8cb",
  "executionRef": "Parity_Best_7K2M9QH4TR8DXZ",  // quote this to Parity support
  "clientOrderId": "your-order-id",
  "externalUserId": "your-player-id",
  "contractId": "ctr_4919562d19a0f299",
  "side": "YES",
  "action": "buy",
  "status": "partially_filled",
  "outcome": "closed_partial",      // complete | closed_partial | closed_unfilled
  "filledQuantity": 24.0,
  "averagePrice": 0.72,
  "fillCount": 2,
  "transmissionState": "resolved",
  "final": true,
  "partial": true,
  "operatorMoney": {                // the order's last word
    "currency": "USD",
    "authorizationAmount": "25.00",
    "actualDebit": "17.49",
    "releaseAmount": "7.51",
    "tradeAmount": "17.28",
    "platformFee": "0.21",
    "venueFee": "0.00",
    "venueFeeKnown": false
  },
  "operatorExitMoney": null,
  "releaseAmount": "7.51",          // HAND THIS BACK
  "currency": "USD",
  "simulated": false
}

{
  "orderId": "3dd27f36-7780-4aa7-8af2-1a6854fbf8cb",
  "executionRef": "Parity_Best_7K2M9QH4TR8DXZ",  // quote this to Parity support
  "clientOrderId": "your-order-id",
  "externalUserId": "your-player-id",
  "reason": "venue refused: market closed",
  "operatorMoney": {                // nothing was spent. release all of it
    "currency": "USD",
    "authorizationAmount": "25.00",
    "actualDebit": "0.00",
    "releaseAmount": "25.00",
    "tradeAmount": "0.00",
    "platformFee": "0.00",
    "venueFee": "0.00",
    "venueFeeKnown": false
  }
}

{
  "orderId": "3dd27f36-7780-4aa7-8af2-1a6854fbf8cb",
  "executionRef": "Parity_Best_7K2M9QH4TR8DXZ",  // quote this to Parity support
  "clientOrderId": "your-order-id",
  "externalUserId": "your-player-id",
  "authorizationAmount": "40.00",   // RESERVE and HOLD. there is no release here
  "currency": "USD",
  "transmitted": false
}

There is deliberately no releaseAmount on a recorded intent. Nothing has been decided yet, and a field meaning “hand this back” on an order whose funds must be held would be the wrong instruction at the wrong moment. order.cancelled is the event that says release.

{
  "orderId": "3dd27f36-7780-4aa7-8af2-1a6854fbf8cb",
  "executionRef": "Parity_Best_7K2M9QH4TR8DXZ",  // quote this to Parity support
  "externalUserId": "your-player-id",
  "cancellationId": "cxl_3dd27f36-7780-4aa7-8af2-1a6854fbf8cb",  // idempotency key for the release
  "currency": "USD",
  "authorizationAmount": "40.00",
  "actualDebit": "0.00",            // always zero: nothing was transmitted
  "releaseAmount": "40.00",
  "reason": "customer withdrew",
  "transmitted": false
}

{
  "positionId": "5c0f7a1e-2b9d-4c6e-8f31-7a4d2e9b6c05",
  "settlementId": "e2a94d17-6c3b-4f80-9d52-1b7e3a6c8f24",     // idempotency key for the credit
  "externalUserId": "your-player-id",
  "contractId": "ctr_4919562d19a0f299",
  "side": "YES",
  "resolution": "YES",
  "outcome": "won",
  "contracts": 15.6451,
  "costBasis": 10.00,               // facts, not instructions
  "entryFees": 0.30,
  "payout": 15.65,
  "realisedPnl": 5.35,
  "lifetimeRealisedPnl": 5.35,
  "operatorMoney": {                // CREDIT THIS
    "currency": "USD",
    "settlementCredit": "15.65",    // winnings
    "voidCredit": "0.00"            // a void: a refund, fee included, or a split payout
  },
  "simulated": false
}

Exactly one of settlementCredit and voidCredit is non-zero, and a loss zeroes both. They are two names because they are two instructions: winnings are revenue against a wager and a void either reverses one (an annulled market, fee included) or pays a split result at its share of a dollar a contract with the fee kept. Collapsing them into a single payout would push that distinction onto you to re-derive from the outcome string.

{
  "contractId": "ctr_4919562d19a0f299",
  "settledResolution": "YES",       // what you were settled on
  "currentResolution": "NO",        // null when the outcome was withdrawn
  "affectedPositionIds": [           // every position of yours it touches
    "5c0f7a1e-2b9d-4c6e-8f31-7a4d2e9b6c05",
    "9a2e4b7c-1d3f-4e5a-8b6c-0f9e8d7c6b5a"
  ],
  "affectedPositionId": "5c0f7a1e-2b9d-4c6e-8f31-7a4d2e9b6c05",  // the first of them
  "action": "operator_review_required"
}

The dedupe key of each event

Treat every key as opaque and compare it whole. The formats are shown so you can see what makes two events the same fact, not so you can parse them. The <operator> part is an opaque token that is stable for your operator; events recorded before it was introduced carry your operator id there instead, and are never raised a second time under the new form.

{
  "id": "<eventId>",
  "type": "position.settled",
  "dedupeKey": "position.settled:<positionId>",
  "createdAt": "2026-08-21T18:02:11.004Z",
  "data": { ... }
}

content-type: application/json
parity-signature: t=1755751331,v1=<hex hmac-sha256 of "<t>.<body>">
parity-event-type: position.settled
user-agent: Parity-Webhooks/1

The event is identified by id in the body, which is the same on every attempt, so no per-attempt header is needed. The signature timestamp t is taken afresh for each attempt, so a retry carries a new signature over the same data.

• dedupeKey is the natural key of the fact, not of the attempt to report it. Key your own processing on it. At-least-once is the only guarantee an HTTP retry can offer, and this is what makes that safe.
• Answer 2xx quickly and process asynchronously. A delivery times out at 10 seconds.
• Redirects are never followed, and a 3xx is treated as a delivery failure. A redirect is a destination nobody verified.
• createdAt is stamped when this attempt is sent, not when the fact happened. It moves between retries of the same event, so it is a delivery timestamp and must not be used to order events or to date the underlying fact. No payload carries a timestamp of its own: date the fact from the resource it names (for example GET /api/v1/orders/{id}) or from the reconciliation feed.

The timestamp is inside the signed material, not merely alongside it. A signature over the body alone is replayable forever: anyone who observes one valid delivery can resend it a year later and it still verifies. The tolerance is 300 seconds.

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

export function verify(secret: string, body: string, header: string, toleranceSeconds = 300) {
  const parts = new Map(header.split(',').map((p) => p.split('=') as [string, string]));
  const t = Number(parts.get('t'));
  const v1 = parts.get('v1');
  if (!Number.isFinite(t) || !v1) return false;

  // An old signature is refused even when the MAC is perfect. That is the whole
  // purpose of putting the timestamp in the signed material.
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - t) > toleranceSeconds) return false;

  const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest();
  const given = Buffer.from(v1, 'hex');
  if (given.length !== expected.length) return false;
  return timingSafeEqual(expected, given);
}

• Where the secret comes from. Parity registers your endpoint and issues its signing secret once, at that moment; no read returns it again. Store it in your secret manager immediately. Rotating it issues a new one the same way and replaces the old one at once. There is no overlap window: every delivery from that moment, including retries of events raised before it, is signed with the new secret. Plan a rotation as a short outage of verification, and deploy the new secret as soon as it is issued; deliveries that fail verification in between are retried on the normal schedule.
• Verify against the raw body, before any JSON parsing. Re-serialising changes the bytes and the MAC will not match.
• Verify parity-signature. Each delivery also carries the same signature under an earlier header name, for endpoints written against the earlier docs, so checking one is enough.
• Signing secrets are prefixed whsec_ and are encrypted at rest under a key held outside the database.
• An unsigned delivery is never sent. If signing is unavailable the attempt counts as a failure and is retried on the schedule below, rather than sent in the clear.

• Six attempts over 22 hours 35 minutes, measured end to end by a test that walks a delivery through the whole schedule.
• Every failed attempt uses one of the six, whatever the cause: a non-2xx answer, a timeout or network error, a redirect, a destination that fails the checks below, or signing being unavailable. A destination whose host is not registered with Parity therefore exhausts after the full schedule.
• The first attempt goes out on the next drain of the queue, which runs every 15 seconds by default. A delivery claimed by a worker that then dies is picked up again after 30 minutes, which is one more reason a delivery can arrive late or twice.
• An endpoint stays registered however many deliveries fail. A delivery to an endpoint that has been made inactive is held, not dropped, and resumes if the endpoint is made active again.
• The tail is deliberately long. An endpoint that has been down for ten hours is having an incident, and hammering it every minute helps nobody.
• A delivery is pending, sending, delivered or exhausted. exhausted is terminal for the schedule, and the delivery is kept: Parity replays any exhausted delivery on request.

A partner-supplied URL is an attacker-influenced outbound request from inside Parity's network, so the destination rules are strict and are re-checked on every attempt rather than once at registration, because DNS can be repointed afterwards and a retry hours later is exactly when that would be exploited.

• https only, on port 443. No credentials in the URL.
• The hostname must be registered with Parity for your account. Any other host is refused.
• Every resolved address must be public unicast. Loopback, private ranges, link-local (cloud instance metadata), carrier-grade NAT and multicast are all refused, and every address is checked, not just the first.

DNS rebinding is closed. The connection is made to an address the check validated, the name is not resolved a second time, TLS is verified against the hostname, and redirects are not followed.

A destination that fails a check is refused with one of these reasons:

Refused ranges: 0.0.0.0/8, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 100.64.0.0/10, the documentation ranges 192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0/24, and everything from 224.0.0.0 up; for IPv6, ::, ::1, fe80::/10, fc00::/7, ff00::/8, 2001:db8::/32 and 3fff::/20. An IPv4 address written inside IPv6 is unwrapped and checked as IPv4.

Webhook endpoints are a managed service. Send your webhook URLs and event types to your account team; we register them and confirm. Signed-in members of your team with write access can also manage them on your account's configuration page (the Webhook endpoints section). Per endpoint, we need:

• The URL. It must pass the destination rules above, and its host is registered with Parity for your account as part of registering the endpoint.
• The event types it wants. An empty list means every type, including any added later.

Every attempt is recorded per endpoint with its status code, so when a delivery has not arrived your account team can tell you exactly what your endpoint answered, and replay it.