Webhooks (push events)

Webhooks are the realtime channel ProphetX exposes — there is no websocket option, and ProphetX would prefer ISVs not poll the REST API for state changes. Register a receiver and ProphetX pushes async events — contract updates, contract settlements, market-order state changes, matched-order fills, parlay state changes, fixtures lifecycle (sport events, tournaments, markets), market-selection liquidity snapshots, wallet transactions, and KYC status changes — to a URL you operate. You register one base URL per ISV, and ProphetX appends a fixed path to it for each event type.

Orderbook updates. If you're looking for orderbook / depth-of-market data, that's the MarketSelectionEvent on /push/market-selections (section 4.9). The event structure mirrors the market-maker websocket feed; only the transport differs (webhook instead of websocket).

Auth:

  • On the management endpoints in this doc: ISV-only JWT (see Authentication).
  • On inbound webhook deliveries to you: ProphetX-issued JWT signed by the push service. You should verify it on your end before trusting the payload.

1. Registration endpoints

MethodPathPurpose
POST/private/v1/push/register{ "baseUrl": "https://partner.example.com" } — register your receiver root.
GET/private/v1/push/registerReturns the current registration if one exists.
DELETE/private/v1/push/registerStop receiving. Effective immediately.
POST/private/v1/push/test{ "type": "contract" | "contract_settlement" | "market_order" | "parlay" | "event" | "tournament" | "market" | "market_selections" | "transaction" | "kyc_status" } — fires a test message and reports round-trip latency. matched_order cannot be triggered from this endpoint — you'll only see that event type on real activity.

POST /push/register returns:

  • 201 on success.
  • 409 if you're already registered. To change the URL: DELETE first, then re-POST.

There is no per-event-type subscription. Once you're registered, you receive all event types.

POST /push/test response shape:

{ "success": true, "latencyMs": 142 }

error is omitted entirely on success. When present, it's populated either because the test couldn't reach you at all (connection refused, timeout) or because your receiver responded with an unexpected non-2xx status.


2. What your receiver must implement

Your baseUrl must expose these paths:

MethodPathWhy
GET/healthCalled before resuming delivery after a pause. Return 200 when ready.
POST/push/contractsContractEvent — contract created / updated / deleted.
POST/push/contract-settlementsContractSettlementEvent — contract settled.
POST/push/market-ordersMarketOrderEvent — market order created / updated / deleted.
POST/push/matched-ordersMatchedOrderEvent — fires once per fill against a resting order. op is "created" or "test" only.
POST/push/parlaysParlayEvent — parlay created / updated / deleted.
POST/push/eventsSportEventEvent — sport-event lifecycle (status / schedule changes).
POST/push/tournamentsTournamentEvent — tournament create / update / delete.
POST/push/marketsMarketEvent — market metadata (status / strike changes). Lightweight; for liquidity use /push/market-selections.
POST/push/market-selectionsMarketSelectionEvent — liquidity snapshots. op is "updated" or "test" only.
POST/push/transactionsTransactionEvent — a wallet transaction was recorded. op is "created" or "test" only.
POST/push/kyc-statusKycStatusEvent — a user's KYC application was opened or its status changed.

All POST events share one envelope.


3. The event envelope

{
  "id": 8291,
  "op": "created" | "updated" | "deleted" | "test",
  "timestamp": "2026-04-01T12:00:00Z",
  "data": { "...": "event-type-specific payload" }
}
  • id is monotonically increasing within an event type — not across types. It doesn't give you an order between, say, a MarketOrderEvent and a ContractSettlementEvent. Use it to dedupe (delivery is at least once, so you may receive duplicates) and to order same-type events against each other (a higher id for the same type wins). See section 6 for what ordering guarantee you actually get across event types.
  • op = "test" indicates a test message sent via POST /push/test. Treat it as a no-op or a connectivity probe; don't apply state changes.

4. Event payloads

4.1 ContractEvent → POST /push/contracts

{
  "id": 8291,
  "op": "updated",
  "timestamp": "...",
  "data": {
    "eventId": 999999,
    "marketId": 219,
    "outcomeId": 4,
    "contractId": "8315d4bc44d06eef736959e0b214c170",
    "name": "Winner (incl. overtime)",
    "type": "moneyline",
    "price": -110.0,
    "priceFormats": {
      "american": -110,
      "decimal": 1.9091,
      "cents": 52.38,
      "probability": 52.38
    },
    "adjustedPrice": -115.0,
    "adjustedPriceFormats": {
      "american": -115,
      "decimal": 1.8696,
      "cents": 53.49,
      "probability": 53.49
    },
    "strike": 0.0,
    "status": "active",
    "favourite": false,
    "updatedAt": "2026-04-01T12:00:00.000Z"
  }
}

op semantics for contracts:

  • created — new contract, or new price available.
  • updated — status or favourite changed.
  • deleted — contract no longer available.

status is one of active, suspended, settled. price and adjustedPrice may be null if no liquidity exists yet.

priceFormats and adjustedPriceFormats are present only when the ISV has additional price formats enabled, and omitted when the corresponding price is null. american is canonical and the only format the exchange accepts on input — decimal, cents, and probability are display-only views derived from it and do not round-trip to an exact American price. Do not build order guardrails from derived formats.

4.2 ContractSettlementEvent → POST /push/contract-settlements

{
  "id": 9001,
  "op": "created",
  "timestamp": "...",
  "data": {
    "contractId": "8315...",
    "result": "profit",
    "eventId": 999999,
    "marketId": 219,
    "outcomeId": 4,
    "strike": 0.0
  }
}

result is one of profit, loss, push, void. This is the signal to mark the relevant orders' winningStatus in your own database.

When a settlement is written. A settlement is written for an outcome and strike only when it has matched orders to grade. Three consequences:

  • A contract nobody traded never gets a settlement push and never appears on the settlements endpoint. Use MarketEvent with status: settled and SportEventEvent with status: closed as the terminal signal for those, and resolve untraded entries on your side.
  • Resting orders that never matched are cancelled when the event closes. You see that on MarketOrderEvent, not here.
  • When ops grade a strike, the settlement is written for the outcome they graded. Orders on the opposite outcome at the same strike are graded through the match, so the opposite contract may not get a settlement of its own. If you receive a settlement for one side of a strike, resolve the other side with the inverse result (profit ↔ loss; push and void apply to both sides).

Resettlements arrive as a new message with the corrected result. Settlement pushes are broadcast messages and subject to the buffer cap in section 6, so reconcile from GET /private/v1/sport-events/{eventId}/settlements (see Fixtures section 5) after any delivery pause.

The event fires when the settlement is requested, before the wallet is credited, so the matching PAY / PUSH / VOID transaction in GET /private/v1/transactions can arrive a short interval after this webhook.

Settlement change on November 30, 2026. result keeps the same four values, but on Not Pushable markets (moneyline, spread, total and game props) push and void no longer mean "cost returned". A tie on those markets settles at $0.50 per contract and arrives as result: "push"; a cancellation settles at Fair Market Value and arrives as result: "void". Pushable markets (player props) are unchanged. This payload carries no amount, so until the settled-price field below ships, take the credited value from the PUSH / VOID transaction (its amount), not from the order's cost — see Wallets.

Upcoming field. A settled-price field is being added to data on this event and to the settlements endpoint so the value is available without consulting the ledger. It will be optional and absent on profit / loss and on traditional cost-returning pushes. The field name will be published here and in the OpenAPI spec once it is live in sandbox; clients should already tolerate unknown keys in data.

contractId is not always guaranteed to match the contractId you traded on. For markets created through ProphetX's admin tooling for manually-created events, this event's contractId can be recomputed at settlement time using a different formula than the one used when you placed the order, with no mapping back to the original value (tracked as BBPX-160). If you're reconciling settlements against your own order records, match on eventId + marketId + outcomeId + strike rather than relying on contractId alone.

4.3 MarketOrderEvent → POST /push/market-orders

{
  "id": 9100,
  "op": "updated",
  "timestamp": "...",
  "data": {
    "id": "isv_xyz",
    "userId": "...",
    "contractId": "8315...",
    "quantity": 24.50,
    "unfilledQuantity": 0,
    "filledQuantity": 24.50,
    "refundedQuantity": 0,
    "expectedAveragePrice": -110,
    "currentAveragePrice": -108,
    "currentAveragePriceFormats": {
      "american": -108,
      "decimal": 1.9259,
      "cents": 51.92,
      "probability": 51.92
    },
    "nextAveragePrice": -107,
    "settlementStatus": "tbd",
    "fillStatus": "filled",
    "status": "completed",
    "createdAt": "...",
    "updatedAt": "..."
  }
}

Same shape as GET /private/v1/market-orders/{refId}, wrapped in the envelope. The data.id here is the order's refId.

4.4 MatchedOrderEvent → POST /push/matched-orders

Fires once per fill against a resting order. Distinct from MarketOrderEvent (which tracks the lifecycle of a single submitted order) — this event is the per-fill signal you'd reconcile against your own trade ledger. op is "created" or "test" only; fills don't update or delete.

{
  "id": 9250,
  "op": "created",
  "timestamp": "...",
  "data": {
    "contractId": "8315d4bc44d06eef736959e0b214c170",
    "eventId": 999999,
    "marketId": 219,
    "outcomeId": 4,
    "strike": 2.5,
    "originStrike": -2.5,
    "price": -110.0,
    "priceFormats": {
      "american": -110,
      "decimal": 1.9091,
      "cents": 52.38,
      "probability": 52.38
    },
    "fillPrice": -108.0,
    "fillPriceFormats": {
      "american": -108,
      "decimal": 1.9259,
      "cents": 51.92,
      "probability": 51.92
    },
    "filledQuantity": 50.0,
    "sequenceNumber": 42
  }
}

Field meanings:

  • price — the price the resting order was originally placed at.
  • priceFormats — price expressed in every supported format. Present only when the ISV has additional price formats enabled.
  • fillPrice — the price this specific fill matched at (may improve on price).
  • fillPriceFormats — fillPrice expressed in every supported format. Present only when the ISV has additional price formats enabled.
  • filledQuantity — quantity matched in this fill.
  • strike — the handicap/spread for the contract (0 for moneyline markets).
  • originStrike — the home-team-perspective strike for spreads/totals. null on moneyline.
  • sequenceNumber — monotonically increasing. Use it to order fills chronologically when receiving multiple events on the same contract.

/push/test doesn't currently fire matched-order events. The TestPushRequest.type enum is contract | contract_settlement | market_order | parlay | event | market | tournament | market_selections | transaction | kyc_status — no matched_order. You'll only see real MatchedOrderEvents once a fill actually occurs.

This event is best effort — it is never retried, same as MarketSelectionEvent below. A MatchedOrderEvent your receiver fails to accept is simply gone; there's no replay. If you need a complete, gapless fill ledger, reconcile periodically against your own order/position records rather than relying on this stream alone.

4.5 ParlayEvent → POST /push/parlays

Fires when a parlay is created (i.e. after confirm) or updated (fill state changes, settlement, etc.).

The real trigger is "linked to a money transaction," not strictly "confirmed." This event only fires once ProphetX can resolve the parlay's identity via a BET wallet transaction tied to its ref_id — if no such transaction exists yet, the event is silently skipped. In practice this almost always lines up with the parlay reaching its confirmed state, but the two live in separate systems with a brief reconciliation window between them, so don't assume perfect simultaneity with GET /private/v1/parlays/{parlayId} showing confirmed — if you need certainty, poll that endpoint rather than relying solely on this event's timing.

{
  "id": 9300,
  "op": "updated",
  "timestamp": "...",
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "userId": "...",
    "settlementStatus": "profit",
    "settledAt": "...",
    "createdAt": "...",
    "updatedAt": "..."
  }
}

settlementStatus is one of profit, loss, push, tbd. For the full parlay state (fill status, fee, quantities, legs), call GET /private/v1/parlays/{parlayId} — the webhook is a lightweight signal that something changed, not a complete snapshot. See Parlays (2–12 leg trades).

4.6 SportEventEvent → POST /push/events

{
  "id": 9400,
  "op": "updated",
  "timestamp": "...",
  "data": {
    "id": 20023797,
    "status": "live",
    "startTimeTbd": false,
    "sportId": 2,
    "categoryId": 0,
    "name": "Detroit Pistons at Cleveland Cavaliers",
    "scheduled": "2026-05-15T23:00:00Z",
    "tournamentId": 132,
    "seasonId": null,
    "roundId": null,
    "updatedAt": "..."
  }
}

status values: not_started, live, suspended, ended, closed, cancelled, interrupted, postponed, abandoned, delayed. Fires when an event's status flips (e.g. into live), when scheduling changes, or when it's removed. Use it to drive UI like "this event is in-play now".

This webhook is also the authoritative close signal. GET /private/v1/sport-events only lists events that are tradable right now, so an event dropping out of that list does not mean it is over (see Fixtures section 3.1). Close an event in your own records when you receive this message with status of ended, closed, cancelled or abandoned. suspended, postponed, delayed and interrupted are temporary and the event normally comes back.

This event never carries a reason or explanation for the status change — for any status, not just cancelled/postponed/interrupted/abandoned. There's no reason/free-text field on this payload today, and none upstream either — don't build a UI that waits for one to show up later. For general policy on how non-standard cases are settled (delays, interruptions, a player not starting, etc.), point your users to ProphetX's settlement rulebook — it covers categories of rules, not the specific reason behind any one event.

4.7 TournamentEvent → POST /push/tournaments

{
  "id": 9500,
  "op": "created",
  "timestamp": "...",
  "data": {
    "id": 132,
    "name": "NBA",
    "sportId": 2,
    "categoryId": 0,
    "updatedAt": "..."
  }
}

Tournament-level CRUD. Most ISVs will only care about created (a new tournament appeared and you may want to surface it in your catalog) and deleted.

4.8 MarketEvent → POST /push/markets

{
  "id": 9600,
  "op": "updated",
  "timestamp": "...",
  "data": {
    "id": 186,
    "eventId": 20023797,
    "status": "suspended",
    "strike": 0,
    "name": "Moneyline",
    "updatedAt": "..."
  }
}

status values: active, canceled, inactive, settled, skipped, suspended. This is metadata only — no prices, no resting orders. For liquidity, listen on /push/market-selections (next).

4.9 MarketSelectionEvent → POST /push/market-selections

The liquidity feed. Fires whenever the resting orders on a market change — new orders posted, fills, voids, or cancels. op is always "updated" (or "test" for the connectivity probe) — there's no create/delete for selections.

{
  "id": 9700,
  "op": "updated",
  "timestamp": "...",
  "data": {
    "eventId": 20023797,
    "tournamentId": 132,
    "market": {
      "id": 186,
      "name": "Moneyline",
      "type": "moneyline",
      "strike": 0,
      "sequenceNumber": 12483,
      "selections": [
        [
          {
            "outcomeId": 4,
            "competitorId": 101,
            "name": "Cleveland Cavaliers",
            "displayName": "Cleveland Cavaliers",
            "contractId": "8315d4bc44d06eef736959e0b214c170",
            "strike": 0,
            "displayStrike": "0",
            "price": -110,
            "priceFormats": {
              "american": -110,
              "decimal": 1.9091,
              "cents": 52.38,
              "probability": 52.38
            },
            "displayPrice": "-110",
            "adjustedPrice": -115,
            "adjustedPriceFormats": {
              "american": -115,
              "decimal": 1.8696,
              "cents": 53.49,
              "probability": 53.49
            },
            "quantity": 50,
            "value": 45.45,
            "updatedAt": "..."
          }
        ],
        [
          {
            "outcomeId": 5,
            "competitorId": 102,
            "name": "Detroit Pistons",
            "displayName": "Detroit Pistons",
            "contractId": "abc123...",
            "strike": 0,
            "displayStrike": "0",
            "price": +100,
            "priceFormats": {
              "american": 100,
              "decimal": 2.0000,
              "cents": 50.00,
              "probability": 50.00
            },
            "displayPrice": "+100",
            "adjustedPrice": 95,
            "adjustedPriceFormats": {
              "american": 95,
              "decimal": 1.9474,
              "cents": 51.35,
              "probability": 51.35
            },
            "quantity": 25,
            "value": 25,
            "updatedAt": "..."
          }
        ]
      ]
    }
  }
}

Notes on the shape:

  • selections is a list of lists — same shape as GET /private/v1/markets. Each inner list is one side of the book, ordered best-price-first, capped at 10.
  • adjustedPrice/adjustedPriceFormats, competitorId, displayName, displayPrice, and displayStrike are all optional and omitted when not applicable (e.g. no ISV fee configured, or no competitor on this outcome) — same semantics as the equivalent fields on ContractEvent.
  • sequenceNumber is per-market and monotonic. If you receive an event with a sequenceNumber lower than the last one you processed for the same market.id, drop it — it's an out-of-order delivery.
  • This is a snapshot, not a delta. Each event replaces your view of the market's resting liquidity entirely.
  • quantity and value are distinct: quantity is the resting stake on the other side of the selection, value is that same liquidity scaled by odds — the amount actually available for you to take. Prefer value when sizing against available liquidity. See the Selection field table.
  • You can fire a test event for this path via POST /push/test with { "type": "market_selections" }.

4.10 TransactionEvent → POST /push/transactions

Fires when a wallet transaction is recorded. The ledger is append-only, so op is always "created" (or "test" for the connectivity probe) — there's no update/delete for transactions.

{
  "id": 9800,
  "op": "created",
  "timestamp": "...",
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "userId": "...",
    "type": "BET",
    "amount": "-24.50",
    "balanceBefore": "100.00",
    "balanceAfter": "75.50",
    "contractId": "8315...",
    "refId": "isv_xyz",
    "createdAt": "..."
  }
}

type is one of DEPOSIT, WITHDRAW, APPROVE_WITHDRAW, REJECT_WITHDRAW, BET, CANCEL, PAY, PUSH, VOID, REFUND, ORDER_FEE, REFUND_FEE, COMMISSION, ADJUSTMENT_INCREASE, ADJUSTMENT_REDUCE, JOURNAL_DEPOSIT, JOURNAL_WITHDRAW. userId is absent for ISV-level transactions (e.g. DEPOSIT/WITHDRAW on a STANDING-fund pot). contractId and refId are absent when not applicable to the transaction type. COMMISSION is defined but not currently fired for ISV transactions — order fees arrive as ORDER_FEE/REFUND_FEE instead; see Wallets.

4.11 KycStatusEvent → POST /push/kyc-status

Fires when a user's KYC application is opened, and again whenever its status changes.

{
  "id": 9900,
  "op": "updated",
  "timestamp": "...",
  "data": {
    "userId": "...",
    "kycStatus": "FAILURE",
    "canRetry": true,
    "failReason": "document_unreadable",
    "updatedAt": "..."
  }
}

kycStatus is one of PENDING, PHOTO_VERIFICATION_PROCESSING, SUCCESS, FAILURE, MORTALITY, PEP, OFAC. PENDING and PHOTO_VERIFICATION_PROCESSING are in-flight; the rest are terminal for the current attempt, and only SUCCESS promotes the applicant to a verified user. canRetry is only ever true for FAILURE, and only while retries remain (see KYC testing for the retry cap). failReason is present only for FAILURE, MORTALITY, PEP, and OFAC, and only when the provider supplied one.


5. A small naming inconsistency: fillStatus

  • Private API (GET /market-orders/{refId}.fillStatus): filled | open | partial
  • Webhook (MarketOrderEvent.data.fillStatus): filled | resting | partial

It's the same underlying state, just a different word for "not yet filled." Treat open and resting as synonyms.


6. Delivery, ordering, retries, and pausing

Each event type is delivered on its own independent stream — a burst of one type (e.g. market_selections) doesn't delay another (e.g. market_order).

Ordering differs by category:

  • market_order, parlay, transaction, and kyc_status are delivered in order per user: one user's events arrive in the order they happened, and different users' events can be in flight at the same time.
  • contract, contract_settlement, market, event, and tournament are sent a few at a time and can arrive slightly out of order. When several updates to the same contract/market/event/tournament are queued at once, only the newest is sent — the rest are coalesced away, not delivered individually.
  • market_selections and matched_order are best effort and never retried — see the row below. A missed market_selections update is simply replaced by the next one; discard anything that arrives with an out-of-order sequenceNumber.

Delivery guarantee: at least once — a redelivery (e.g. after a restart on ProphetX's side) can resend something you already processed, so dedupe on id.

BehaviorDefault
Delivery timeout5 seconds — your receiver must respond 2xx within this window.
RetriesA 5xx or a timeout is retried with backoff. A 429 is retried after its Retry-After header. A 404 is treated as accepted — not retried, not counted as an error. Any other 4xx (400/401/403/422) is rejected outright: not retried, and delivery moves on to the next event. market_selections and matched_order are never retried, regardless of status.
Per-event give-upIf one specific event keeps failing while other events of its same type are being accepted fine, that event is given up on after a bounded number of attempts — so one event your receiver can't handle doesn't hold back everything behind it.
Error thresholdAfter 4 consecutive failures, your receiver as a whole is paused and ProphetX stops sending anything further.
ResumeProphetX polls GET /health; when it returns 200, delivery resumes.
Max message age24 hours. Messages older than this are dropped, not delivered.
Buffer capBroadcast-type messages (contract, contract_settlement, event, tournament, market, market_selections, matched_order) are buffered in memory per ISV, up to 50,000 at a time. If the buffer is full when a new one arrives, it's dropped and never replayed. User-scoped messages (market_order, parlay, transaction, kyc_status) are persisted instead and aren't subject to this cap.

Keep your receiver fast and answer 2xx. The buffer only fills when deliveries stall. During a stall, market_selections keeps arriving at roughly 100 messages per second, so a receiver that returns 5xx even a few percent of the time will pin the buffer at its cap and silently lose event, market, and settlement webhooks. Accept the message, queue it internally, and respond 2xx immediately; do your processing afterwards. Resync from the fixtures API after any pause.


7. Verifying inbound calls came from ProphetX

Each delivery carries a JWT signed by the push service (Ed25519). The push service's public key (or JWK endpoint) is provisioned by ProphetX out of band. Your handler should verify:

  1. Signature against the configured public key (EdDSA / Ed25519). The key differs between sandbox and production; ProphetX sends you each one when the environment is provisioned.
  2. iss is prophetx in every environment.
  3. aud is your ISV UUID, so it changes between sandbox and production along with your UUID.
  4. exp is valid against your clock. Tokens expire 5 minutes after issue. (There is no nbf claim on these tokens.)

Reject anything that doesn't pass — return non-2xx and ProphetX will retry. Don't act on unverified payloads.


8. Receiver implementation checklist

  • GET /health returns 200 when ready (and 5xx when you've intentionally paused).
  • All eleven POST paths are wired to handlers that parse the same envelope. A 404 on any of them is treated as a silent no-op by ProphetX — it won't be retried and it won't count toward the error threshold, so a missing handler goes unnoticed. If you don't need an event type yet, wire an empty handler that returns 200 so you can see it in your logs.
  • Inbound JWT verified on every request.
  • Events deduped on id — a higher id for the same entity wins.
  • For /push/market-selections, additionally drop events with an out-of-order data.market.sequenceNumber.
  • Handlers are idempotent — the same event may arrive more than once.
  • Responses go out in under 5 seconds; long-running work happens off the request path.
  • op: "test" is recognized and never applied to real state.

9. Curl

BASE="https://isv-api.sandbox.prophetx.dev/private/v1"

# Register
curl -X POST "$BASE/push/register" \
  -H "Authorization: Bearer $JWT_ISV" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl":"https://partner.example.com" }'

# Check
curl "$BASE/push/register" -H "Authorization: Bearer $JWT_ISV"

# Test each event type (matched_order isn't supported by /push/test)
for t in contract contract_settlement market_order parlay event tournament market market_selections transaction kyc_status; do
  curl -X POST "$BASE/push/test" \
    -H "Authorization: Bearer $JWT_ISV" \
    -H "Content-Type: application/json" \
    -d "{\"type\":\"$t\"}"
done

# Unregister
curl -X DELETE "$BASE/push/register" -H "Authorization: Bearer $JWT_ISV"

Did this page help you?