Event Ingestion

Send events from a trusted backend to POST /events/ingest. This endpoint uses HMAC headers, not bearer authentication.

Supported event types#

| Category | Event types | | --- | --- | | Account | user_created, login_event | | Order | order_created, order_canceled | | Payment | payment_failed, payment_succeeded, payment_captured | | Refund | refund_requested, refund_completed | | Dispute | dispute_opened, chargeback_received |

Event contract#

| Field | Requirement | | --- | --- | | companyId | VertexY company UUID. | | eventSource | Sending service name. | | externalEventId | Stable event ID from your system. | | idempotencyKey | Reuse when retrying this event. | | userId | Stable user ID from your system. | | eventType | A supported value above. | | timestamp | ISO 8601 event time. | | metadata | Business context for the event. |

Optional enrichment fields are paymentDetails, billingAddress, shippingAddress, cardDetails, deviceMeta, and ipGeo. See Objects and Dictionary for exact fields.

Canonical example#

{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "eventSource": "checkout-service",
  "externalEventId": "evt_payment_10492",
  "idempotencyKey": "evt_payment_10492",
  "userId": "usr_8f7b2c9a4d",
  "eventType": "payment_succeeded",
  "timestamp": "2026-05-18T10:30:00.000Z",
  "metadata": { "orderId": "ord_10492", "channel": "web" },
  "paymentDetails": {
    "methodType": "card",
    "provider": "stripe",
    "fingerprint": "pmh_visa_44e9",
    "amountMinor": 12999,
    "currency": "USD",
    "authStatus": "authorized"
  }
}

Sign the exact serialized body and send a fresh timestamp and nonce for every HTTP attempt. See Signing and Reliability and Retries and Idempotency.