Webhook Management Guide

This guide was designed to assist you in understanding the utilization of webhooks for real-time data receipt from the Impilo platform. Webhooks serve as a powerful automation tool that allows your systems to be integrated with Impilo. This allows immediate data retrieval as events are triggered within the platform.

Understanding Webhooks

Webhooks are HTTP callbacks defined by the user. They are designed to be triggered by specific events on the Impilo platform. When an event is triggered, Impilo sends an HTTP POST request to the webhook’s configured URL. This request contains details related to the event, enabling your system to react in kind.

Setting Up Webhooks

Webhook setup requires you to supply Impilo with a URL endpoint capable of handling POST requests. This is where the webhook payloads will be delivered.

Creating a Webhook

Creation of a webhook involves interaction with the “Create Webhook” endpoint. This requires you to indicate the types of events you are interested in monitoring and to provide a URL to handle event notification delivery.

Webhook Types

Name	Desciption
procurement.statusFull	A procurement status event occurred. The payload includes the full procurement model.
supportTicket.event	A support ticket event took place.
reading.bloodOxygen	A reading of blood oxygen was taken.
order.status	An order status event occurred. The payload only includes order id and order event type.
reading.peakFlow	A peak flow reading was taken.
transferRequest.statusFull	A transfer request status event occurred. The payload includes the full transfer request model.
device.lowBattery	A device sent a low battery signal.
return.statusFull	A return status event was triggered.
patient.updated	A patient’s details were updated.
reading.sleepMatActivity	A sleep mat activity reading was taken.
reading.bloodPressure	A reading of blood pressure was taken.
reading.sleepMatDuration	A sleep mat duration reading was taken.
procurement.status	A procurement status event occurred. The payload only includes procurement id and event type.
device.associationCreated	A patient-device association was created.
device.associationRemoved	A patient-device association was removed.
patient.created	A new patient was created.
reading.weight	A body weight reading was taken.
reading.temperature	A body temperature reading was taken.
transferRequest.status	A transfer request status event occurred. The payload only includes transfer request id and transfer request event type.
return.status	A return status event was triggered.
reading.bloodGlucose	A reading of blood glucose was taken.
device.weakSignal	A device sent a weak signal.
order.statusFull	An order status event occurred. The payload includes the full order model.

Consuming a Webhook

When your application receives a webhook request from Impilo, inspect the ‘type’ attribute to identify the event trigger. The first part of the event type will reveal the payload type, e.g., patient created, order status updated, etc.

Example Payload

1 {
2     "id": 57638473,
3     "type": "patient.created",
4     "payload": {}
5 }

Security

To verify that a webhook was sent by Impilo, you can configure a webhook secret that Impilo will send on each notification. The webhook secret is passed in a header with name Impilo-Webhook-Secret. You can manage your webhook secret via API or in your account portal.

Webhook secret request:

Webhook secret response:

Webhook Retries

Intervals

In situations where a webhook delivery attempt to your endpoint fails, the Impilo platform automatically retries sending the webhook notification according to a defined schedule. The first retry occurs 15 minutes after the initial failed delivery, the second retry occurs 30 minutes following the first retry, and the third retry occurs 60 minutes after the second retry.

Monitoring Webhook Attempts and Retries

To monitor and troubleshoot webhook deliveries, including retries, the Webhook Log endpoint provides comprehensive logs. You can query these logs with several filterable parameters to better understand the delivery status and manage your webhook activities effectively. Details about these parameters are available in the Webhook Log section of the API documentation.

Webhook logs request:

Webhook logs response:

Walkthroughs

To facilitate user understanding on the use of webhooks in real-world scenarios, this guide includes various case studies on potential webhook applications. Real code examples and implementations are provided to give a practical understanding of webhook implementation.

Placeholders

In all subsequent examples, ‘https://example.com/webhook’ is used as a placeholder for your webhook URLs

Patient Reading Events

The ‘reading.*’ webhook types can be utilized to receive patient reading data via webhook. Depending on the type of reading data you wish to receive, you can use one of the following for the ‘type’ parameter.

Name
`reading.bloodGlucose`
`reading.bloodOxygen`
`reading.bloodPressure`
`reading.temperature`
`reading.weight`

To get notifications on new weight readings, you can create a device webhook through the webhook endpoint.

POST /api/v3/webhook

$ curl -X POST http://app.impiloplatform.com/api/v3/webhook \
> -H "Content-Type: application/json" \
> -d '{"type":"reading.weight","url":"https://example.com/webhook"}'

Going forward, the recorded weight readings of Impilo will be forwarded to ‘https://example.com/webhook’ in the following format.

Example Payload

1 {
2     "id": 57638473,
3     "type": "reading.weight",
4     "payload": {
5         "id": 1,
6         "readingTimestamp": "readingTimestamp",
7         "weight": 1.1,
8         "manual": true,
9         "patient": {},
10         "item": {},
11         "device": {},
12         "site": {}
13     }
14 }

For pulling readings and more information about weight readings, see the weight reading section of the API Reference.

Webhook Testing

Using Webhook Tests

The Impilo API provides several endpoints for testing different types of webhook events. These endpoints allow you to simulate real-world events and observe how your system handles the incoming webhook payloads. This is particularly useful for debugging and ensuring that your webhook handlers are working correctly.

First create a webhook using the above instructions. Then, fire a test event for the desired event type.

Test Blood Pressure Webhook

For example, to trigger a test blood pressure webhook, use the following endpoint:

More endpoints are available in the tests section of the api reference.

Webhook API Reference

Weight Reading API Reference

1	{
2	"id": 57638473,
3	"type": "patient.created",
4	"payload": {}
5	}

$	curl -X POST http://app.impiloplatform.com/api/v3/webhook \
>	-H "Content-Type: application/json" \
>	-d '{"type":"reading.weight","url":"https://example.com/webhook"}'

1	{
2	"id": 57638473,
3	"type": "reading.weight",
4	"payload": {
5	"id": 1,
6	"readingTimestamp": "readingTimestamp",
7	"weight": 1.1,
8	"manual": true,
9	"patient": {},
10	"item": {},
11	"device": {},
12	"site": {}
13	}
14	}