Events and analytics

Events connect provider delivery with recipient behaviour. SDKs can report notification lifecycle events, your application can report business events, and outcomes can attach numeric value to a conversion.

Submit an event#

POST /v1/events

{
  "event_type": "opened",
  "notification_id": "b39ddcd7-2892-4c3d-8145-0ce3bc9e3ec4",
  "device_id": "0e83059e-715d-45b8-911b-30d36519c863",
  "occurred_at": "2026-09-16T14:22:08Z",
  "metadata": {
    "action_id": "view_order"
  }
}

Accepted event types are:

custom and outcome require event_name of up to 120 characters. notification_id and device_id are optional UUIDs, but when present they must belong to the authenticated app.

The response is 202 Accepted:

{"accepted":true}

Custom events#

Use custom events for meaningful product behaviour, not every UI interaction. They can drive segment membership and start event-triggered journeys.

{
  "event_type": "custom",
  "event_name": "checkout.abandoned",
  "device_id": "0e83059e-715d-45b8-911b-30d36519c863",
  "metadata": {
    "basket_id": "basket_441",
    "currency": "GBP"
  }
}

Event names may be used in segment fields such as custom_event.checkout.abandoned. Establish a consistent naming convention before integrating several clients.

Outcomes and value#

Outcome events measure conversions. Put an optional numeric amount in metadata.value.

{
  "event_type": "outcome",
  "event_name": "purchase",
  "notification_id": "b39ddcd7-2892-4c3d-8145-0ce3bc9e3ec4",
  "device_id": "0e83059e-715d-45b8-911b-30d36519c863",
  "metadata": {
    "value": 49.95,
    "currency": "GBP"
  }
}

An outcome with a notification ID is recorded as direct; one without it is unattributed. HoneyNotify aggregates the numeric value but does not perform currency conversion, so do not combine different currencies under one outcome name unless your application normalises them first.

Event timing and duplication#

If occurred_at is omitted, the API uses the current time. Prefer the real client occurrence time for offline or delayed uploads.

The event endpoint is not idempotent. Avoid double submission in client callbacks, and use your application state to deduplicate revenue outcomes when that matters to reporting.

Notification event history#

GET /v1/notifications/{notification_id}/events?page=1&limit=50

This returns a paginated event stream scoped to one notification, including each event's source, properties, and occurrence time.

Aggregate analytics#

GET /v1/analytics?days=30

days is clamped between 1 and 365 and defaults to 30. The response contains daily metrics grouped by event type and platform, plus outcomes grouped by name and attribution.

{
  "metrics": [
    {"metric_date":"2026-09-15","event_type":"opened","platform":"ios","total":184}
  ],
  "outcomes": [
    {"name":"purchase","attribution":"direct","total":12,"value":"748.40"}
  ],
  "days": 30
}

Provider acceptance, device confirmation, and user engagement answer different questions. Report them separately rather than labelling all accepted sends as delivered.