OpenPoly logo
Webhooks

Event envelope

Shared event envelope for all webhook deliveries.

Event envelope

Every webhook payload uses same outer envelope.

Example

{
  "event_id": "4f35af6b-6aa3-4a6d-bc6f-9a5b24ad7bb0",
  "event_type": "mini_app.trade.processed",
  "operator_id": 12,
  "occurred_at": "2026-06-18T00:00:00.000Z",
  "aggregate_type": "mini_app_order",
  "aggregate_id": "123",
  "idempotency_key": "mini_app_order:123:processed",
  "data": {
    "order_id": 123,
    "trade_id": 456,
    "executed_trade_id": 456,
    "operator_id": 12,
    "operator_user_id": 34,
    "polynion_user_id": 789,
    "external_user_id": "operator-user-123",
    "market_id": 51,
    "side": "buy",
    "outcome": "yes",
    "status": "processed",
    "requested_external_amount_minor": 10000,
    "requested_shares_micro": null,
    "quoted_credits_equivalent": 6340,
    "quoted_external_amount_minor": 10000,
    "shares_micro": 1234500,
    "balance_spent": 10000,
    "trade_fee": 39,
    "trade_fee_credits": 25,
    "currency_code": "IDR",
    "fx_rate_snapshot_id": 88,
    "failure_reason": null
  }
}

Fields

FieldTypeMeaning
event_idstringGlobally unique event identifier. Primary dedupe key on receiver side.
event_typestringBusiness event name.
operator_idnumberOpenPoly operator record ID for routing and audit.
occurred_atstringUTC ISO timestamp when event became true.
aggregate_typestringResource family behind event, such as mini_app_order.
aggregate_idstringAggregate identifier, always serialized as string.
idempotency_keystringStable event-level idempotency key from OpenPoly side.
dataobjectEvent-specific payload only.

Invariants

  • event_id unique across all webhook events
  • aggregate_id always string, even if underlying DB key numeric
  • data shape depends on event_type
  • trade event data is reconstructed from durable order/user/operator/trade rows when possible
  • no API key, wallet secret, launch token, or session secret in payload
  • no raw internal transaction token in payload
  • legacy trade fields credits_delta and external_amount_minor are not emitted in trade callback data
  • trade_fee is historical fee in integer minor units of currency_code; trade_fee_credits is same fee denominated in Credits

Receiver guidance

  • store full envelope with raw body hash if audit required
  • dedupe by event_id, not by aggregate_id
  • route business logic by event_type
  • use aggregate_type and aggregate_id for correlation, not dedupe

Related pages

Signatures

Verify webhook signatures and reject replays safely.

Event types

Business events sent by OpenPoly to operator webhook receivers.

Copyright © 2026