Webhooks let Qliva notify your external systems in real time when specific events happen in your clinic.
What are webhooks?
A webhook is an HTTP POST request that Qliva sends to a URL you configure whenever a specific event occurs — for example, when an appointment is booked, an invoice is paid, or a patient signs a consent document.
Instead of your system polling Qliva for changes, Qliva pushes the notification to you the moment it happens.
Common use cases
- Sync Qliva data to an external database or data warehouse
- Trigger automated workflows in Zapier, Make, or n8n
- Update your own CRM or patient management system
- Send custom notifications when key events occur
Available webhook events
| Event | When it fires |
|---|---|
appointment.created | A new appointment is booked |
appointment.updated | An appointment is modified |
appointment.cancelled | An appointment is cancelled |
invoice.paid | An invoice is marked as paid |
invoice.created | A new invoice is created |
pathology.results_released | Pathology results are released to a patient |
form.completed | A patient completes an intake form |
consent.signed | A patient signs a consent document |
membership.created | A patient enrolls in a membership |
membership.cancelled | A membership is cancelled |
prescription.signed | A prescription is signed |
Webhook payload
Every event delivers a JSON payload to your endpoint. The payload includes the relevant resource data (the appointment, invoice, form, etc.) and a tenant_id field that identifies which clinic triggered the event.
This is useful if you're building a multi-clinic integration — you can use tenant_id to route incoming payloads to the right clinic in your system.
Security — HMAC signature validation
Every webhook request includes an X-Qliva-Signature header containing an HMAC-SHA256 signature of the raw request body, signed with your webhook's secret key.
You must validate this signature on your receiving server before processing any payload.
To validate:
- Retrieve the raw request body (before parsing)
- Compute
HMAC-SHA256(body, your_signing_secret) - Compare the result to the value in
X-Qliva-Signature - If they don't match, reject the request with a 401
Your signing secret is shown once when you create the webhook endpoint in Qliva. Save it somewhere secure — it cannot be retrieved again. If you lose it, delete the endpoint and create a new one.
Always validate the HMAC signature before processing webhook payloads. Do not process payloads from unknown or unverified sources — anyone can POST to your endpoint URL if you don't check the signature.
Configuring webhooks
- Go to Admin Portal → Settings → Developer → Webhooks
- Click Add Endpoint
- Enter your endpoint URL (must be publicly reachable over HTTPS)
- Select the events you want to receive
- Copy and save the signing secret shown on creation
Your endpoint should return a 2xx HTTP status code to acknowledge receipt. Return any non-2xx status and Qliva will treat the delivery as failed.
Retry behaviour
If your endpoint returns a non-2xx response, or doesn't respond within the timeout window, Qliva will retry delivery up to 5 times using exponential backoff.
If your endpoint continues to fail after all retries, the webhook will be automatically disabled. You'll need to re-enable it from the Webhooks settings page once your endpoint is back online.
Webhook delivery is best-effort. If your endpoint is consistently unreachable, the webhook will be disabled automatically. Check your endpoint logs regularly and set up monitoring on your receiving server.