Introduction

The Luscii FHIR Webhooks API provides subcribing systems with data events for alerts (Flags), measurements (Observations), and Patients. In this guide you will learn how to configure your system to start receiving and processing such events.

📔

MDD / MDR Verification

In order to integrate the FHIR Webhooks API, your connected product must meet our criteria for connected products because you will be receiving medical information from our EU certified Medical Device. Get in touch with us for more information.

Features

Security

Each webhook is set up with a shared secret. This is used by Luscii to produce a HMAC signature, and by you to verify this signature. The shared secret is a fixed value, the signature is dynamically generated.

An optional Authorization HTTP header can be specified during set up, which you can use to authenticate the request using for example an API key. This is always a fixed value.

See Authentication for more details.

Failures and Retries

The requirements for a successful response are:

  • The connection must be established within two seconds.
  • The response must be received within 10 seconds after establishing the connection.
  • The response status code must be between 200 and 299 inclusive.

If any of these requirements are not met, a retry is automatically scheduled, see below. We do not make any distinction between status codes in the 400 range and in the 500 range; in both cases we will retry.

If a failure occurs we support automatic retries. The time in-between tries follows an exponential backoff: 1 minute, 2 minutes, 4 minutes, 8 minutes, 16 minutes, (...). The maximum number of retries is 5, making a total of 6 tries per message. If the last try fails, an error will be raised to our team and we will contact you.

It's important to note that a message may be delivered more than once! For example if the response from your server was slow, we have no way of knowing whether it was successful. The message may have been successfully processed in this case, but we will still send it again. This means that you are responsible for deduplication. We will ensure that each retried message is identical to the original message. (Same HTTP headers and body.) For deduplication you can use the unique identifier we send in the payload (see examples below, how identifiers are represented depend on the format), or the signature in the header, or you can ensure that processing on your side is idempotent.

Format

We support HL7 FHIR XML.

Multiple events

We support various Luscii events. Webhooks can be set up to listen to one or more of these events, so that you can choose which ones you want to integrate. Note that you may set up multiple subscribers; for example to receive different events on separate URI's.

ResourceEventDescription
FlagAlertCreatedAn alert was triggered
FlagAlertEscalatedAn alert was escalated by a first-line to the second-line healthcare professional
FlagAlertProcessedAn alert was processed (= closed)
ObservationObservationCreatedA patient has submitted a new measurement
PatientPatientActivatedA patient was enrolled in Luscii
PatientPatientDeactivatedA patient was deactivated in Luscii
PatientPatientUpdatedPatient information was updated in Luscii