Webhook endpoints API

A webhook endpoint is an https URL you register to receive events as they happen. neolife signs every delivery with your endpoint's whsec_… secret and posts a PHI-free body — ids and status only. All paths below are under /v1/developer/webhooks.

For the delivery model, signature verification, and retry semantics, see Webhooks & events.

List subscribable event types#

The catalog of event types an endpoint can subscribe to.

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

["order.shipped", "intake.submission.created"]

Subscribe to a subset when you create or update an endpoint. See Events for what each type carries.

Create an endpoint#

POST /v1/developer/webhooks. Register an https URL and the events it should receive. The url must be https; an unknown event type or a non-https host returns 400.

curl -X POST https://api.neolife.health/v1/developer/webhooks \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" \
  -H "Idempotency-Key: 3f1b0c2a-9d6e-4a51-8b2f-1c7e5a9d0e42" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/neolife",
    "events": ["order.shipped", "intake.submission.created"]
  }'

{
  "id": "whe_1a2b3c",
  "url": "https://example.com/hooks/neolife",
  "events": ["order.shipped", "intake.submission.created"],
  "status": "enabled",
  "secret": "whsec_9f8e7d6c5b4a3210fedcba9876543210"
}

The secret is returned exactly once — at creation. Store it now; it's the key you verify every delivery's signature against. If you lose it, delete the endpoint and create a new one. Later reads (GET) never return the secret.

Omit events to subscribe to none — you can add them later with a PATCH. Send an Idempotency-Key so a retried create doesn't register a duplicate endpoint.

List endpoints#

GET /v1/developer/webhooks. Every configured endpoint for your tenant, oldest first. Secrets are not included.

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

[
  {
    "id": "whe_1a2b3c",
    "url": "https://example.com/hooks/neolife",
    "events": ["order.shipped", "intake.submission.created"],
    "status": "enabled"
  }
]

Update an endpoint#

PATCH /v1/developer/webhooks/{id}. Partially update the url, the subscribed events, or the status. Send only the fields you're changing. An unknown id returns 404.

To disable an endpoint without deleting it — deliveries stop, but the endpoint and its secret are preserved so you can re-enable later — set status:

curl -X PATCH https://api.neolife.health/v1/developer/webhooks/whe_1a2b3c \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "disabled" }'

status is "enabled" or "disabled". Re-subscribe events the same way:

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

The response is the updated endpoint (without its secret).

Delete an endpoint#

DELETE /v1/developer/webhooks/{id}. Permanently removes the endpoint and invalidates its signing secret. Deliveries stop immediately. An unknown id returns 404.

curl -X DELETE https://api.neolife.health/v1/developer/webhooks/whe_1a2b3c \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

{ "deleted": true, "id": "whe_1a2b3c" }

Prefer PATCH … "status": "disabled" if you want to pause an endpoint and keep the same secret.

Send a test event#

POST /v1/developer/webhooks/{id}/test. Fires a sample signed event at the live endpoint and returns the delivery result — the fastest way to confirm your URL is reachable and your signature verification is correct before real traffic arrives.

curl -X POST https://api.neolife.health/v1/developer/webhooks/whe_1a2b3c/test \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

{
  "delivered": true,
  "statusCode": 200,
  "durationMs": 142
}

The test payload is synthetic and carries no PHI, exactly like production deliveries.

List recent deliveries#

GET /v1/developer/webhooks/{id}/deliveries. The last 50 delivery attempts for an endpoint, newest first — use it to debug failures and confirm what was sent.

curl https://api.neolife.health/v1/developer/webhooks/whe_1a2b3c/deliveries \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

[
  {
    "id": "whd_88ff01",
    "event": "order.shipped",
    "statusCode": 200,
    "success": true,
    "attemptedAt": "2026-07-06T14:22:31Z"
  }
]

Related#

• Webhooks & events — the reconciliation model, signing, and verification.
• Events API — the durable, PHI-free event log you can also pull and replay.
• API reference — base URL, versioning, errors, and rate limits.