CloudEvents and Payload Shapes#

All Webhook deliveries use CloudEvents 1.0 structured JSON with content type application/cloudevents+json.

tsinterface ArteryCloudEvent<TData> {
  specversion: '1.0';
  id: string;
  source: string;
  type: string;
  subject: string;
  time: string;
  datacontenttype: 'application/json';
  dataschema: string;
  qfeventtype: string;
  qfcorrelationid: string;
  qfrevision: number;
  qforganizationid: string;
  traceparent?: string;
  data: TData;
}

Dispatch on the versioned CloudEvent type. Use qfeventtype for product grouping, id for delivery deduplication, and qfcorrelationid plus qfrevision to order corrections to the same business entity.

Delivery headers#

• X-Artery-Signature: HMAC-SHA256 signature over the exact raw body
• X-Artery-Admission: pre-body admission proof; receivers may verify it to reject unauthenticated slow uploads
• X-Artery-Delivery-Id: identity of this delivery attempt stream
• X-Artery-Event-Id: equal to the CloudEvent id
• X-Artery-Event-Type: versioned CloudEvent wire type, equal to type
• X-Artery-Attempt: current delivery attempt number

Artery treats any 2xx response as success and retries other outcomes with exponential backoff. A retry preserves the exact event identity and body.

Both proofs use t=<unix-seconds>,v1=<hex-hmac>. Verify X-Artery-Signature by computing HMAC-SHA256 over ${t}.${rawBody} with the Webhook secret, comparing in constant time, and rejecting stale timestamps (five minutes is the recommended tolerance). The admission proof signs admission.${t} and complements, but never replaces, raw-body verification.

Canonical market snapshot#

Account-scoped Order, Trade, Settlement/Redeem, and Liquidation events carry the same immutable market display snapshot. Activity responses reuse this shape. Identity, filtering, and deduplication continue to use stable IDs; titles and outcome labels are display data captured when the event is created.

tsinterface CanonicalMarketRef {
  providerMarketId: string | null;
  symbol: string | null;
  universalId: string | null;
  conditionId: string | null;
  title: string | null;
  eventTitle: string | null;
  slug: string | null;
  eventSlug: string | null;
  url: string | null;
  imageUrl: string | null;
  outcome: {
    tokenId: string;
    index: number;
    label: string | null;
  } | null;
  metadataAsOf: string | null;
}

Every property is present. A nullable value means enrichment was unavailable; it does not make the financial event incomplete. Gamma failures never block durable event persistence or Webhook delivery, and the delivery worker never calls Gamma. Historical deliveries keep their original snapshot after catalog metadata changes.

Activity taxonomy#

GET /v1/me/activity returns a generated discriminated union. Dispatch on type, and use activityType for the user-facing category:

Polymarket settlement is not liquidation. A normal losing close is still a trade; Loss is a settlement result. Title-less Polymarket events remain in bounded asynchronous enrichment and are not delivered with a raw condition or token ID as user-visible text.

Versioned Event Types#

The live event catalog API is authoritative. The following anchors correspond to each catalog docsUrl; use each version's schemaUrl for the exact data shape.

market.trade.executed

market.spread.updated

broker.trade.executed

broker.order.updated

broker.funding.updated

broker.position.settlement.updated

portfolio.balance.updated

portfolio.performance.updated

portfolio.cashflow.updated

broker.position.liquidated

signal.arbitrage.detected

signal.trade-volume.detected

signal.spread-widening.detected

signal.wallet-burst.detected

signal.settlement-delay.detected

market.settlement.updated

market.settlement-dispute.updated