Manage webhook endpoints

Once an endpoint is receiving deliveries, the work is mostly upkeep: rotating its secret, changing which events it receives, and moving older endpoints onto named events.

Who can change an endpoint

An endpoint belongs to the person who created it, not to your company. Only its owner can edit it, delete it or rotate its secret, and the owner’s own data access decides what it can deliver. Your company’s administrators can view every member’s endpoints, but cannot change them.

Rotate the signing secret

1. On the Notifications tab, regenerate the endpoint’s secret.
2. For the next 24 hours, every delivery is signed with both the new and the old secret, and X-Webhook-Signature lists both.
3. Switch your receiver to the new secret at any point in that window.

Because your receiver accepts a match against any listed signature, no delivery is rejected during the switch.

Change an endpoint’s events

Open Edit events and scope on the endpoint, tick or untick events or whole groups, adjust the scope, and save. The change applies to the next event.

Two events come from a run rather than from a record changing:

Clinical data added (clinicalData.added) tells you a run found something new. siteSonar.completed and patientHistories.completed tell you a run finished, which happens whether or not the patient’s record grew. This event carries counts of what is new, by type, and a run that found nothing sends nothing. Webhook endpoints only. A run reports a batch of patients; each endpoint is sent only the patients its scope covers.

AI research completed (aiResearch.completed) tells you an AI research run that you started has finished. A colleague’s endpoint does not receive it, and the endpoint’s project scope does not apply, since a researched site belongs to no project.

A patient enrolled in more than one product gets one clinicalData.added per product, and each delivery’s source says which. Each count covers only that product’s run, so take the larger figure rather than adding them up.

Both are delivered like every other named event: signed with a timestamp, carrying X-Webhook-Id and version: "events", and retried until your receiver acknowledges them.

Upgrade a Classic endpoint

An endpoint created before named events is a Classic endpoint, shown with a deprecation banner. It keeps working unchanged. Select Upgrade to Events to see, for each of its subscriptions, the events it becomes, which of its columns are still in a payload without triggering anything, and which are in no payload at all. Classic subscriptions could each have their own scope; the upgrade uses the broadest of them, and the preview says so. Confirm, and the endpoint switches to named events in one step, keeping its URL, secret and headers.

On a Classic endpoint, the two run events above are picked from the Events group at the end of the subscription builder’s Entity dropdown, as clinicalDataAdded and aiResearchCompleted. Those are delivered differently:

• The body has only eventType and data: no id, timestamp, resource, changed or version.
• They are sent once, with no retry, and never disable the endpoint.
• They are signed with X-Webhook-Signature, but carry no X-Webhook-Id to deduplicate on.

Next steps

• Receive webhook events: the events, the payload and verification.
• Handle webhook retries and failures: retries, auto-disable and reconciliation.