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
POSTper 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:
| Field | Type | Description |
|---|---|---|
webhookUrl | string | HTTPS endpoint Vivlio Health will POST events to |
webhookEnabled | boolean | Turns 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):
PUT /ext/latest/client
Content-Type: application/json
Authorization: Bearer {partner_token}{
"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
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:
| Event | Fired When |
|---|---|
parsed-data.created | A 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:
POST {your webhookUrl}
Content-Type: application/json
X-Webhook-Signature: sha256={hmac-hex-digest}{
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"event": "parsed-data.created",
"timestamp": "2026-08-03T14:32:01.000Z"
}| Field | Type | Description |
|---|---|---|
patientId | string | The patient the event pertains to |
event | string | Event type — see table above |
timestamp | string | ISO 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:
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
2xximmediately and process asynchronously on your side if needed). Anything other than a2xxresponse, 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
patientIdif 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/timestampmore than once). - If
webhookEnabledisfalseorwebhookUrlis unset, events for your account are simply skipped — no queued backlog is delivered retroactively when you re-enable it.
Troubleshooting
| Symptom | Likely Cause |
|---|---|
| No webhooks received | webhookEnabled is false, webhookUrl is unset, or set on the wrong (non-partner) client record |
| Signature never matches | Signing with the wrong secret, or re-serializing the body before hashing |
| Missed events during prolonged downtime | Delivery 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 |
