Ingestion

Track one product event

Records a single product event for the app's user. Event meaning is versioned by event_code: if the meaning of an event ever changes (what it counts, or when the host app emits it), the host must emit a new event_code. Existing codes are never redefined. Events sent with only an anonymous_id attach to an anonymous user, which is listed on the dashboard but not evaluated until an identify call promotes it. For an app that ingests asynchronously, the request is validated, durably accepted into the ingest buffer and answered 202 with {"event":{"mapping_status":"pending"},"processing":"queued"}: no event, user or job yet, since the event is applied shortly after, in the order the app's requests were accepted. Failures that need the database (a derived event code, a contact-rule violation) are then not answered to the caller; they are dead-lettered (see the dashboard ingest dead-letters endpoint). A retried request with the same context.$message_id is still deduplicated. Events from known crawlers and bots (the request's User-Agent, or the event's context.user_agent) are answered 202 with the queued shape but dropped without being stored (INGEST_DROP_BOTS).

post/v1/events/track

Request

  • Base URL: https://api.whisperr.net
  • URL: https://api.whisperr.net/v1/events/track
  • Auth: API key in header Authorization

Request body

anonymous_idstring

Opaque per-device handle (UUID v4, rotated by the SDK's reset()) for a visitor who has not identified yet. Trimmed; printable characters only. The event attaches to the anonymous user behind the handle, or to the identified user a later identify call promoted it into.

contextobject
event_typestring required

Project event code. Runtime mapping is app-scoped.

external_user_idstring

The customer's own user id. Optional when anonymous_id is sent.

occurred_atstring date-time

Optional event timestamp. When omitted, whisp-go uses the receive time.

propertiesobject

Example request

{
  "event_type": "checkout_completed"
}

Response

Event accepted and evaluation job enqueued, or, for an app that ingests asynchronously, event durably queued.

OR

Example response

{
  "job": {
    "type": "evaluate_user"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.