Store event API contract

Send signed commerce events from your store backend. The API derives the tenant from the API key, validates consent fields, and stores each event through a tenant-scoped repository.

This endpoint is server-to-server only. Never expose a whh_live_ key in browser JavaScript or a public tracking snippet. Production use also requires the committed MySQL migrations to be applied.

Event endpoint

POST /api/v1/events

Authorization: Bearer whh_live_... tenant key
Idempotency-Key: Required; 8–191 safe characters
X-WWWHive-Timestamp: Required Unix time in seconds; five-minute window
X-WWWHive-Signature: HMAC-SHA256 of timestamp.rawBody

Accepted event names

product_viewcart_createdcart_updatedcheckout_startedpurchase_completedcustomer_created

Request and field mapping

The JSON body requires eventId, type, payload, and ISO-8601 occurredAt. Optional fields are customerId, cartId, value, and currency. A currency is required when value is present; customer creation must include payload.marketingConsent.

eventId: Merchant ID → external_event_id
customerId: Merchant ID → external_customer_id
occurredAt: Merchant time → occurred_at
tenantId: Never accepted; derived from the hashed API key

Responses

A new event returns 202 with eventId, accepted, and receivedAt. An idempotent replay returns 200 and X-Idempotent-Replay: true. Errors return code, message, requestId, and optional fieldErrors. Expected error statuses are 400, 401, 413, 422, 429, and 503.