Webhooks & events

neolife tells you what's happening with your orders in two complementary ways: webhooks (pushed to your endpoint) and the event log (which you pull). Both are PHI-free — ids and status only.

Register an endpoint#

Create a webhook endpoint in the dashboard or via the API. You'll get a signing secret (whsec_…) once — store it.

curl -X POST https://api.neolife.health/v1/developer/webhooks \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/neolife/webhooks", "events": ["order.shipped"] }'

An empty events array subscribes to everything.

Event types#

Event	When
order.routed	neolife dispatched the order to a pharmacy.
order.submitted	The pharmacy accepted it.
order.rejected	A pharmacy declined it (with a reason code).
order.shipped	A shipment with tracking exists.
order.delivered	Delivered to the patient.

Payloads look like:

{ "type": "order.shipped", "id": "evt_1a2b3c",
  "data": { "orderId": "ord_123", "pharmacyConnectionId": "pc_9", "status": "shipped" } }

Verify the signature#

Every delivery is signed. Verify it before acting — reject anything that doesn't match your secret.

import { verifyWebhook } from "@neolifehealth/sdk";

app.post("/neolife/webhooks", async (req, res) => {
  const event = verifyWebhook({
    payload: req.rawBody,
    headers: req.headers,
    secret: process.env.NEOLIFE_WEBHOOK_SECRET!,
  }); // throws if the signature is invalid

  if (event.type === "order.shipped") {
    // PHI-free — fetch details you need over the authenticated API
    const order = await neolife.orders.get(event.data.orderId);
  }
  res.sendStatus(200);
});

Return a 2xx quickly; do slow work afterward. neolife retries non-2xx deliveries with backoff.

Reconcile with the event log#

Delivery is at-least-once, and networks fail — so every event is also written to a durable, tenant-scoped event log you can pull and replay. This is your escape hatch after downtime:

# List recent events
curl "https://api.neolife.health/v1/developer/events?limit=50" \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

# Re-deliver one to your subscribed endpoints
curl -X POST https://api.neolife.health/v1/developer/events/evt_1a2b3c/replay \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

Receivers should dedupe on the event id — a replay (or an at-least-once retry) can deliver the same event more than once.

Local development#

The CLI can stream your live events to a local receiver so you can build and test a real webhook handler without a public URL.