OpenPoly logo
Webhooks

Event envelope

Shared event envelope for all webhook deliveries.

Event envelope

Every webhook payload uses same outer envelope.

Example

{
  "event_id": "evt_01JY3P4S4TB8A3QGQ95E9W0D2M",
  "event_type": "mini_app.trade.processed",
  "operator_id": 12,
  "occurred_at": "2026-06-18T00:00:00.000Z",
  "aggregate_type": "mini_app_order",
  "aggregate_id": "1",
  "idempotency_key": "mini_app_order:1:processed",
  "data": {
    "order_id": 1
  }
}

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
  • no API key, wallet secret, launch token, or session secret in payload
  • no raw internal transaction token in payload

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