Overview

What is a webhook?

A webhook is an HTTP POST request that Patiro sends to your application’s API whenever a specific event occurs. This mechanism allows Patiro to notify your system immediately, removing the need for you to check for updates manually.

Note: All datetime values included in webhook payloads use the ISO 8601 format.

Webhook payload

The contents of the webhook are POSTed as a JSON document. All payloads include the eventId, eventType, timestamp and the data of the event.

• timestamp - when the event occured
• data - the data of the event, depending on the type of the webhook

{
  "eventId": "bf53700f-2f48-4034-af11-08de8be82d24",
  "eventType": "PatientUpdated",
  "timestamp": "2026-03-27T10:04:03.4247725",
  "data": {
    ...
  }
}

Securing your webhook

For Patiro to communicate with your application, you must expose a publicly accessible URL. It’s important to secure this URL so that malicious actors cannot tamper with your data.

Basic HTTP authentication

A straightforward way to secure your API endpoint is to use basic HTTP authentication. Most web servers can be configured to require a username and password for access to a given URL.

You can protect your webhook endpoint by embedding the credentials into the URL, for example:

https://<username>:<password>@example.com/webhook

Another way to protect your webhook is to create a secure token, and add it as a query parameter to the URL, for example:

https://example.com/webhook?token=<token>

HTTPS required

To ensure all transmitted data is encrypted, using HTTPS (SSL) for your webhook URL is required.

HMAC signature

When creating your webhook callback, you are able to add a signing secret. Patiro will sign all webhooks by computing the hmac signature using the secret. You can use this signature to verify that the webhook is coming from Patiro. Requests that fail verification cannot be trusted and should be discarded.

All webhook notifications that Patiro sends include an x-patiro-hmacsha256 header. The value is computed using:

• the signing secret
• the raw body of the request
• the timestamp included in the x-patiro-timestamp header

Validating the HMAC signature

To validate the signature, generate the HMAC-SHA-256 signature in your own code and compare it to the value in the x-patiro-hmacsha256 header.

1. Grab the signing secret of your webhook. It can be found in the webhook settings page on Patiro PM. An example signing secret could be:

   kI6JBfFdMwOqdxts0bNBKuq6Uqtr6MEcmCSltJItMXqHNTiJbcbJ

2. Extract the x-patiro-timestamp header from the request. Example timestamp:

   1774872805635

3. Concatenate the timestamp and the raw body of the request with a collon : in between. For example, if the body is { "eventId": ... } then the result would be:

   1774872805635:{ "eventId": ... }

   Caution

   Use the raw UTF-8 body of the request, without headers, before deserialising it from JSON or any other forms

4. Hash the resulting string, using the signing secret as the key. In this example, the resulting hash is:

   f2c967cc0fad87be87d7fe2f1d379ccb50ac0433a8a32b7b8a6b2bfa88105120

5. Compare the result with the value in the x-patiro-hmacsha256 header. If they are equal, then the request is verified.

Retry attempts

If Patiro does not receive a 2xx response from your webhook endpoint, we will automatically retry delivering the webhook. If the endpoint responds with 403, we will stop further retries.

Webhooks will be retried on the following schedule:

• 1 min
• 5 mins
• 10 mins
• 15 mins
• 30 mins
• 1 hour
• 2 hours
• 6 hours

The data of the webhook payload is always the latest (or current) version of the data. This also applies when the event is retried. Meaning that if the data has been changed while an event was still scheduled to retry, then the retry attempt will contain the latest data, which might be different from the original event.