Events API

Every state change on your tenant is recorded as an event. The event log is durable and independent of any webhook endpoint, so it's the source of truth you reconcile against: if a callback was missed, dropped, or your receiver was down, you list or replay from here. Events are PHI-free (ids + status), which is what makes exposing the whole log safe — see the PHI boundary.

All routes are under developer/events. They read your tenant's events only, and require a machine API key.

List events#

GET /v1/developer/events

Returns your event log, newest first, cursor-paginated.

Query param	Type	Description
type	string	Filter to a single event type (for example order.submitted).
limit	integer	Page size, 1–100. Defaults to 50.
starting_after	string	Cursor — an event id to page after.

curl "https://api.neolife.health/v1/developer/events?type=order.submitted&limit=20" \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

To page, pass the id of the last event you received back as starting_after:

curl "https://api.neolife.health/v1/developer/events?starting_after=evt_0j5k2p&limit=20" \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

Each entry is the same PHI-free shape neolife signs and delivers to your webhook endpoints — an event id, a type, and a small data object of ids and status.

Get an event#

GET /v1/developer/events/:id

Fetch a single event by id. Returns 404 if no such event exists on your tenant.

curl https://api.neolife.health/v1/developer/events/evt_0j5k2p \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

Stream events live#

GET /v1/developer/events/stream

A Server-Sent Events stream of your tenant's events as they happen. Each SSE message carries one event in the same PHI-free shape as the list and webhook payloads. Keep the connection open and process messages as they arrive:

curl -N https://api.neolife.health/v1/developer/events/stream \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

This stream is what powers neolife listen in the CLI: it signs each streamed event and forwards it to a receiver on your machine, so you can exercise a real webhook handler end-to-end without a public URL.

The stream is for live processing, not durable delivery. Anything you miss while disconnected is still in the log — reconcile with List events or Replay below.

Replay an event#

POST /v1/developer/events/:id/replay

Re-deliver an event to your currently-subscribed webhook endpoints. This is the reconciliation escape hatch: after downtime, replay the events you missed and your normal handler processes them like any other delivery.

By default the event is re-delivered to every subscribed endpoint. Pass an endpointId in the body to target a single one:

curl -X POST https://api.neolife.health/v1/developer/events/evt_0j5k2p/replay \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "endpointId": "whe_2m9x" }'

The response reports how many endpoints the event was re-delivered to:

{
  "delivered": 2
}

Replay is safe to repeat. Each delivery carries the same stable webhook id, so a receiver that dedupes on it (as the webhooks guide describes) will ignore a redundant redelivery. Returns 404 if no such event exists on your tenant.

Reconciliation pattern#

1. Persist the last event id you successfully processed.
2. On startup or after an outage, List events with starting_after set to that id to catch up on everything you missed.
3. For a specific known-missed event, Replay it so your normal webhook handler processes it in-band.
4. In development, Stream (or neolife listen) to watch events flow while you build.

Because every event is PHI-free, none of this pulls patient data into your logs. When you need order or patient detail, hydrate it over an authenticated GET at the moment you use it — see the PHI boundary.

Related#

• Webhooks — subscribe an endpoint, verify signatures, and dedupe deliveries.
• PHI boundary — why the event log carries only ids and status.
• API reference — base URL, versioning, errors, and rate limits.