Skip to content

Webhooks ​

Webhooks let Vivlio Health push event notifications to your system as they happen, instead of you having to poll the API.

Overview ​

  • Webhooks are configured once per partner — the URL and enabled flag live on your partner account's client record, not on individual sub-clients.
  • All clients managed under your partner account share the same webhook URL. Vivlio Health does not currently support per-client webhook endpoints.
  • Delivery is a single HTTP POST per event, signed with an HMAC signature so you can verify the payload came from Vivlio Health.

Configuring Your Webhook ​

Webhook settings are two fields on the client record:

FieldTypeDescription
webhookUrlstringHTTPS endpoint Vivlio Health will POST events to
webhookEnabledbooleanTurns delivery on/off without clearing the URL

Setting the webhook URL ​

Use the self-service client endpoint with your Partner token (a partner authenticates as its own client record, so this updates the partner-level account):

http
PUT /ext/latest/client
Content-Type: application/json
Authorization: Bearer {partner_token}
json
{
  "webhookUrl": "https://yourapp.example.com/webhooks/vivlio",
  "webhookEnabled": true
}

See Client Self-Service for the full field reference.

Partner-Level Only

Webhook fields cannot be set on a sub-client through PUT /ext/latest/partners/clients/{clientId}. Attempting to do so returns a 400 VALIDATION_ERROR with the message: "Webhook settings can only be configured on partner accounts, not sub-clients." Always configure webhookUrl/webhookEnabled via PUT /ext/latest/client while authenticated as the partner.

Verifying the URL is set ​

http
GET /ext/latest/client
Authorization: Bearer {partner_token}

The response includes webhookUrl and webhookEnabled on the client object.

When You Get Notified ​

Vivlio Health currently emits one event type:

EventFired When
parsed-data.createdA patient's medical record retrieval query finishes (COMPLETE) and returns at least one new, non-duplicate file.

Additional event types will be added to this table as they become available — check the Changelog for updates.

No Data, No Notification

If a query completes with zero new files (e.g., no records found, or all results were duplicates of previously retrieved files), no webhook is sent for that query.

Payload Format ​

Each event is delivered as an individual POST request:

http
POST {your webhookUrl}
Content-Type: application/json
X-Webhook-Signature: sha256={hmac-hex-digest}
json
{
  "patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
  "event": "parsed-data.created",
  "timestamp": "2026-08-03T14:32:01.000Z"
}
FieldTypeDescription
patientIdstringThe patient the event pertains to
eventstringEvent type — see table above
timestampstringISO 8601 timestamp of when the webhook was sent

Fetching Details

The webhook payload is intentionally minimal. Use patientId to call Patients or Medical Records endpoints for the full data.

Verifying the Signature ​

Every request includes an X-Webhook-Signature header in the form sha256={digest}, an HMAC-SHA256 digest of the raw JSON body, keyed with the clientSecret for your partner's active API key (the same secret returned once when the key was created — see API Key Management).

Node.js example:

javascript
const crypto = require('crypto');

function isValidSignature(rawBody, signatureHeader, clientSecret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', clientSecret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Use the Raw Body

Compute the signature over the raw request body exactly as received, before any JSON parsing or reformatting — re-serializing the payload can change key order/whitespace and cause the signature check to fail.

Delivery Semantics ​

  • If a delivery attempt to your endpoint fails (non-2xx response, timeout, or network error), it is automatically retried up to 3 times. Retries are not instantaneous — they're driven by the underlying queue, so a retry may land anywhere from under a minute to several minutes after the original attempt.
  • Requests time out after 10 seconds — respond quickly (return 2xx immediately and process asynchronously on your side if needed). Anything other than a 2xx response, a timeout, or a network error counts as a failed attempt and triggers a retry.
  • If all attempts fail, the event is dropped after the 3rd retry and is not delivered again automatically — reconcile via the API using patientId if you suspect a gap.
  • Because retries mean the same event can reach your endpoint more than once, design your webhook handler to be idempotent (safe to process the same patientId/event/timestamp more than once).
  • If webhookEnabled is false or webhookUrl is unset, events for your account are simply skipped — no queued backlog is delivered retroactively when you re-enable it.

Troubleshooting ​

SymptomLikely Cause
No webhooks receivedwebhookEnabled is false, webhookUrl is unset, or set on the wrong (non-partner) client record
Signature never matchesSigning with the wrong secret, or re-serializing the body before hashing
Missed events during prolonged downtimeDelivery is retried up to 3 times, but the event is dropped if your endpoint is still unavailable after that — reconcile via the API using patientId if you suspect a gap

Vivlio Health API Documentation