Webhooks

Thanks to webhooks, your application can be notified by Provet when a certain event occurs.

Webhooks are HTTP POST requests to the URL defined in the settings for each webhook. The POST request has data identifying what type of data was updated, and the ID of the object. For example:

consultation_id=123

Webhooks expect to receive an HTTP 200 response on successful processing. If the response is other than HTTP 200, the notification delivery will be retried up to 10 times.

On the settings page, you can see an up-to-date list of triggered webhooks and their delivery status. A log is available for review.

Webhooks can be set to be department specific, in which case they only trigger when items on a certain department are updated, or can be set to be organization-wide, in which case they always trigger. Leaving the department field empty will make the webhook work across the entire organization.

Certain actions where departments cannot be inferred, such as updating clients and patients through the REST API, do not trigger department-specific webhooks.

Multiple webhooks can be set for the same trigger and/or department, and updates will trigger all of the webhooks that apply in the situation.

Webhooks can be given an optional name to help identify and differentiate them.

No longer needed webhooks can be disabled by unchecking the Active checkbox.

The Webhook events currently available can be seen in Provet settings. Each of the hooks can have a different (or same) URL address, to which Provet sends the hook when triggered by the event.

Configuring Webhooks

Webhooks are configured and enabled in Settings > General > Integrations > Webhooks, or via an API endpoint.

If your integration uses webhooks, we recommend automating webhook creation via an API.

You can view the full list of events you can receive webhooks for here: List of Webhook Triggers.

Webhook filters

Webhooks can optionally be narrowed down with filters. A filter is an opt-in condition stored on the webhook; the event is delivered only if every enabled filter passes. Filters never add events, they only restrict delivery. When multiple filters are enabled on one webhook, all of them must pass.

Filters can be enabled with checkboxes in the webhook settings form, or via the filters field of the webhook API endpoint:

{
    "trigger": 1,
    "url": "https://example.com/webhook/",
    "filters": {"client_has_active_health_plan": true}
}

filters is a single value: a request that sends it replaces the whole config, so send every filter you want the webhook to keep. A request that omits the field keeps what is already stored, including a full update. Send "filters": null, an empty object, or every key as false to remove all of them; over application/x-www-form-urlencoded, where a null cannot be expressed, send filters.<key>=false.

Changing the trigger of a filtered webhook is rejected when a filter you can switch on is not valid for the new trigger: clear the filters or replace them with ones the new trigger accepts.

Filters are released gradually, so a filter may not yet be available to your organization, and a request switching one on is then rejected the same way an unknown key is. A filter already stored on a webhook is reported as it is, and sending it back unchanged is accepted, so a response can always be edited and returned as is. Such a filter does not block a trigger change: it is dropped instead if the new trigger does not accept it. While no filter at all is available to your organization the field is left out of responses entirely, and filters already stored keep restricting nothing until the filter is released to you.

Each filter is only available for specific triggers:

Filter	Trigger	Description
client_has_active_health_plan	1 (Client)	Only deliver client events when the client holds at least one health plan subscription in Active status. Subscriptions in any other status, such as Upcoming, Suspended, Ended or Cancelled, do not count.
invoice_payment_on_health_plan_invoice	11 (Invoice payment)	Only deliver invoice payment events when the paid invoice bills a health plan subscription.
invoice_payment_without_external_id	11 (Invoice payment)	Only deliver invoice payment events when no external ID was recorded for the payment. Payments taken through the health plan API carry the external ID given to it, so this filter leaves the payments recorded in the clinic. Enable it together with invoice_payment_on_health_plan_invoice to be notified of health plan payments collected in the clinic.
patient_has_active_health_plan	2 (Patient)	Only deliver patient events when the patient holds at least one health plan subscription in Active status. Subscriptions in any other status, such as Upcoming, Suspended, Ended or Cancelled, do not count.

The external ID is not reserved for the health plan API: it can be set on any payment through the invoice payment extras endpoint. Setting one on a payment already delivered does not recall that delivery, but it does stop the next event for the same payment, since trigger 11 fires again whenever a payment is modified.

Neither invoice payment filter looks at the amount, so a partial payment and a reversal booked as a negative payment on the same invoice are delivered like any other. A reversal booked by crediting the invoice onto a new one is not: the new invoice bills no subscription of its own, so invoice_payment_on_health_plan_invoice does not pass for payments on it.