🪝Webhooks

What are webhooks?

Webhooks are HTTP callbacks that allow FibriCheck to push data to your application, instead of relying on continuous requests to check for updates or data changes.

In a webhook setup, an HTTP POST request will be sent to a specified URL when a specific event occurs. The callback URL on your side then receives the payload containing relevant data about the event, allowing the receiving application to process and act upon it.

FibriCheck supports webhook events on the following trigger:

• A user performed a new measurement

• A FibriCheck technician reviewed a measurement

• A new summary report is available for a user

Data Structure

The sections below outline the data format our webhook will use when sending information to your webhook endpoint.

Measurements

{
	"eventType": "measurement",
	"measurementId": "",
	"userId": "",
	"extraData": {
		"otherParam": "otherdata"       
	},
	"externalPatientId": "",
	"patientFirstName": "John",
	"patientLastName": "Doe",
	"measurementTimestamp": "2024-11-19T14:37:38Z",
	"status": "analyzed|reviewed",
	"indicator": "normal|quality|urgent|warning",
	"heartRate": 60,
	"mostSevereLabel": {
		"key": "regular|bradycardia|...",
		"color": "green|blue|orange|red|grey"
	},
	"context": {
		"activity": "sitting|standing|...",
		"symptoms": [
			"confused"
		],
		"symptomSeverity": "1"
	},
	"reportUrl": "https://api.fibricheck.com/files/v1/682dc5dd5530b1e811e74bd2-e23a9816-7da8-4406-bae2-f799d0ea60ac/file"
}

Notes

• The measurementId is a unique ID per performed measurement.

• The userId is the FibriCheck userId that can be used to construct the web portal link later on.

• For a single measurement that a user performed, potentially two webhook calls can be triggered. One when the measurement is analysed, and one when the measurement has been reviewed. For both webhook calls, the measurementId value will remain the same.

• The extraData object contains the fields that are stored in the user profile using the fc_data_extra_{TPM_prefix}_* key in the deep link. The key names are converted from snake_case to camelCase.

• The externalPatientId is the identification of the user in the telemonitoring platform, which can be used for mapping the measurement to the correct user. It is mapped from the fc_data_extra_{TPM_prefix}_patient_id key in the deep link.

• Details on the specific values of the different keys can be found here.

• ‼️The context object should be considered optional and can be undefined or only partially filled in when the webhook is executed on an analyzed measurement. This is because if the measurement analysis in the cloud finalizes before the user has provided all the context in the app, the webhook will be triggered before the user has been able to add the context (activity or symptoms). Details on the possible values of the context object can be found here.

Reports

{
    "eventType": "report",
    "reportId": "55e44f3a2902010005e329ce",
    "userId": "5811e231e6e0ab000530a473",
    "groupId": "55273edb46e0fb1035df209f"
    "extraData": {
        "otherParam": "otherdata"       
    },
    "externalPatientId": "",
    "patientFirstname": "John",
    "patientLastname": "Doe",
    "startTimestamp": "2024-11-19T14:37:38Z",
    "endTimestamp": "2024-11-26T14:37:38Z",
    "trigger": "MANUAL|PRESCRIPTION_ENDED|PERIOD_DAYS_PASSED_7|PERIOD_DAYS_PASSED_30",
    "reportUrl": "https://api.fibricheck.com/v1/58e64f3a5908010005e329ce/pdf"
}

Notes:

• The userId is the FibriCheck userId that can be used to construct the web portal link later on.

• The extraData object contains the fields that are stored in the user profile using the fc_data_extra_{TPM_prefix}_* key in the deep link. The key names are converted from snake_case to camelCase.

• The externalPatientId is the identification of the user in the telemonitoring platform, which can be used for mapping the measurement to the correct user. It is mapped from the fc_data_extra_{TPM_prefix}_patient_id key in the deep link.

• The trigger key indicates for what reason the report was generated and has one of the following values:

  • MANUAL - a manual report generation was triggered through the API or through the FibriCheck Portal

  • PRESCRIPTION_ENDED - Report at the end of a prescription

  • PERIOD_DAYS_PASSED_7 - Weekly report during an active prescription

  • PERIOD_DAYS_PASSED_30 - Monthly report during an active prescription

• ‼️The reportUrl link is an API endpoint that needs to be authenticated. This link cannot be used to download the report directly in a browser

Authentication

FibriCheck supports the following authentication methods for calling external webhooks:

• A query parameter in the https URL

• A bearer token in the Authorization header

All webhook requests will originate from the same source IP (environment-specific). This enables you to enable IP whitelisting on the webhook endpoint for additional security. The following IP addresses are in use:

• 👷 Development: 52.48.67.214

• 🇪🇺 EU Production: 52.28.109.191

• 🇺🇸 US Production: 18.224.223.159

Configuration

For security reasons, a webhook can only be configured by FibriCheck staff.

If you want to configure a webhook integration, reach out to your FibriCheck contact or contact us at [email protected].