Skip to main content

​
Webhooks

​
What this is for

Normally your code asks the API for data (“any new patients?”). A webhook flips that: you give ClinikAPI a web address on your own server (an endpoint), and ClinikAPI sends a small message to it the moment something happens, for example when a patient is created. This saves you from repeatedly polling. Each message is signed with a secret that only you and ClinikAPI know, so your server can prove a message really came from us. This page covers the dashboard screen. For the exact message format, headers and how to check the signature in code, see the Webhooks guide.
This page is opened from inside a project, but it shows your webhook endpoints for the whole organization, not just the project you are in.

​
Before you start

  • Webhooks are available on the Pro plan and above.
  • Only an organization owner or admin can add or delete endpoints. Everyone else can see the list.
  • You need a public https address that can receive a POST request, for example https://your-api.com/webhooks/clinik. It cannot be localhost, a private network address or an internal name.
  • Decide which events you want (for example only patient events), and whether the endpoint should receive test traffic.

​
Add an endpoint

1

Open Webhooks

Choose Webhooks in the sidebar. The page is titled Webhooks: “Get notified at your own endpoints when records change.” The list sits in a card titled Endpoints.
2

Open the form

Select Add endpoint in the Endpoints card (or in the empty state if the list is empty). A panel titled Add endpoint opens; on a phone it slides up from the bottom.
3

Enter the Endpoint URL

Type the address into Endpoint URL. The box shows the example https://your-api.com/webhooks/clinik. It must start with https://; the panel shows a message under the box if it does not.
4

Choose where events come from (only if you have sub-organizations)

Deliver events from defaults to All traffic (organization + every sub-org). Choose Only sub-org: (name) to receive only events produced by that sub-organization’s keys. Either way, every message carries the originating tenant in data.tenantId.
5

Choose the environment

Environment can be Both live and test, Live keys only or Test keys only. If your receiver does real work (sending emails, charging people), pin it to Live keys only so test traffic can never trigger it. Every message carries data.environment so your code can tell them apart.
6

Pick events

Under Events to subscribe, All events is on by default. Turn it off to tick individual events; the panel shows how many are selected. They are grouped by area: Individuals, Entities, Clinical Summary, Diagnostics, Medications, Care Provision, Documents, Scheduling, Workflow, Billing, Claims, Insurance and Quality. Each name such as Patient stands for every change to that resource (created, updated, deleted). You must choose at least one.
7

Enable it

Select Add endpoint at the bottom of the panel (it reads Adding… briefly). If something is wrong, the reason appears in the panel and nothing is created. A panel titled Endpoint added shows the signing secret, which starts with whsec_: “Copy the signing secret now. It is shown only this once.” Select Copy secret, store it in your server’s secret manager, then select Done.

​
Rotate the signing secret

Rotate when a secret may have been seen by someone it should not have been, or when you lost it.
1

Open the endpoint

On the Webhooks page, find the endpoint. Its row reads Signing secret: set.
2

Select Rotate secret

Select Rotate secret. A confirmation titled Rotate signing secret warns that the old secret stops working immediately: deliveries signed with it will no longer verify on your server.
3

Confirm and copy the new secret

Select Rotate secret to confirm. A panel titled New signing secret shows the new whsec_ value once. Select Copy secret, put it in your server’s secret manager straight away, then select Done.
Only an organization owner or admin can rotate. Messages already sent keep the signature they were sent with, so any message your server receives after you rotate but before you update it will fail the signature check.

​
Delete an endpoint

Select the bin button at the right of the endpoint’s row (its label is Delete webhook). The confirmation says it will stop sending events to that URL and will also permanently delete the endpoint’s whole delivery history: every past attempt, response code and payload. Select Delete webhook to confirm. A message says Webhook deleted.

​
What you’ll see

  • Each endpoint is a row in the Endpoints card showing its URL and badges: Active, how many events it covers (for example “3 events”), Live keys only or Test keys only if pinned, and a sub-organization’s name if pinned to one. Beneath it: “Signing secret: set. It was shown once and cannot be shown again. To get a new one, rotate it.” with a Rotate secret button (owners and admins only).
  • Empty state: No webhooks configured: “Listen to patient births, new encounters, and integration status changes automatically.”
  • Not on Pro: a box headed Webhooks are a Pro feature: “Real-time event deliveries (signed, with retries) are included on the Pro plan and above. Existing endpoints stop receiving deliveries on lower plans.” with an Upgrade to Pro button. The Add endpoint button is hidden.
  • Not an admin: you see the list but no add or delete controls.
To see whether a delivery succeeded, open the deliveries view in Logs, or watch live in Realtime.

​
Common questions

It is a password used to stamp each message with a signature. Your server recomputes the signature with the same secret; if it matches, the message is genuine. For safety we show it once and store it only in encrypted form, so nobody, including you and us, can read it back. If you lose it, select Rotate secret to get a new one.
Not directly: the address must be a public https URL, and localhost is refused. Use a tunnelling tool that gives your laptop a public https address, and delete that endpoint when you finish.
The endpoint was set to Both live and test. Delete it and add it again with Live keys only.
Deliveries are signed and retried (the plan note says “with retries”). Check the outcome of each attempt in Logs.
Not in the dashboard. To change the URL, events or environment, delete it and add a new one.
Yes. Each choice subscribes you to every kind of change for that resource.

​
Troubleshooting