Skip to content
Eventista Docs

How it works

Network calls fail; clocks drift; requests get retried. The flow below is designed so that, despite all of that, each business event credits EP exactly once — and the credit is applied synchronously, before you get the response.

  1. Your business event fires

    A user completes a qualifying action (an order, a check-in, a campaign event).

  2. You build & sign the request

    Serialize the JSON body once, then compute an HMAC-SHA256 signature over the timestamp and the exact body bytes. See Authentication.

  3. You POST to the award endpoint

    We verify the signature and timestamp window, check the tenant allow-list / caps, convert the raw amount to EP, and de-duplicate by your orderId.

  4. We credit the wallet atomically

    The user credit and the idempotency row are written in one atomic step, so a retry can never double-credit.

  5. We acknowledge with 202

    You receive epTransactionId, status: COMPLETED, and the EP points credited. A replay of the same orderId returns 200 with code: DUPLICATE.

End-to-end flow

Section titled “End-to-end flow”
sequenceDiagram
  participant P as Partner backend
  participant E as Eventista EP engine
  participant L as EP ledger / wallet

  P->>P: Build body, timestamp; sign HMAC-SHA256
  P->>E: POST /v1/ep/webhook (X-Api-Key, X-Timestamp, X-Signature)
  E->>E: Verify signature + timestamp window
  E->>E: Check tenant allow-list, EP enabled, caps
  E->>E: Convert amount to EP, de-dupe by orderId
  E->>L: Credit user (treasury to user) + idempotency row (atomic)
  L-->>E: Committed
  E-->>P: 202 epTransactionId, status COMPLETED, points
  Note over P,E: Retry same orderId returns 200 code DUPLICATE