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.

POST
1curl -X POST https://app.impiloplatform.com/api/v3/webhook \
2     -H "Impilo-API-Key: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "type": "order.status",
6  "url": "https://impilo.health"
7}'
Response
1{
2  "id": 123,
3  "type": "order.status",
4  "url": "https://impilo.health"
5}

Webhook Types

NameDesciption
procurement.statusFullA procurement status event occurred. The payload includes the full procurement model.
supportTicket.eventA support ticket event took place.
reading.bloodOxygenA reading of blood oxygen was taken.
order.statusAn order status event occurred. The payload only includes order id and order event type.
reading.peakFlowA peak flow reading was taken.
transferRequest.statusFullA transfer request status event occurred. The payload includes the full transfer request model.
device.lowBatteryA device sent a low battery signal.
return.statusFullA return status event was triggered.
patient.updatedA patient’s details were updated.
reading.bloodPressureA reading of blood pressure was taken.
procurement.statusA procurement status event occurred. The payload only includes procurement id and event type.
device.associationCreatedA patient-device association was created.
device.associationRemovedA patient-device association was removed.
patient.createdA new patient was created.
reading.weightA body weight reading was taken.
reading.temperatureA body temperature reading was taken.
transferRequest.statusA transfer request status event occurred. The payload only includes transfer request id and transfer request event type.
return.statusA return status event was triggered.
reading.bloodGlucoseA reading of blood glucose was taken.
device.weakSignalA device sent a weak signal.
order.statusFullAn 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:

POST
1curl -X POST https://app.impiloplatform.com/api/v3/webhook-secret \
2     -H "Impilo-API-Key: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{}'

Webhook secret response:

Response
1{
2  "secret": "secret"
3}

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:

GET
1curl -G https://app.impiloplatform.com/api/v3/webhook/logs \
2     -H "Impilo-API-Key: <apiKey>" \
3     --data-urlencode startLastRetryTimestamp=2022-03-10T16:15:50Z \
4     --data-urlencode endLastRetryTimestamp=2022-03-10T16:15:50Z \
5     --data-urlencode startTimestamp=2022-03-10T16:15:50Z \
6     --data-urlencode endTimestamp=2022-03-10T16:15:50Z

Webhook logs response:

Response
1{
2  "content": [
3    {
4      "webhookId": 1,
5      "webhookType": "order.status",
6      "webhookUrl": "http://webhookserver.com",
7      "payload": "{'id':1234}",
8      "createTimestamp": "2023-08-22T14:15:30Z",
9      "lastResponseStatus": 200,
10      "retryAttempts": 3,
11      "lastRetryTimestamp": "2023-08-22T14:15:30Z"
12    }
13  ],
14  "page": 1,
15  "size": 1,
16  "total": 1,
17  "first": true,
18  "last": true
19}

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:

POST
1curl -X POST https://app.impiloplatform.com/api/v3/test/blood-pressure-webhook \
2     -H "Impilo-API-Key: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "patientId": 1,
6  "systolic": 120,
7  "diastolic": 80,
8  "heartRate": 100
9}'

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

More

Webhook API Reference
Weight Reading API Reference
Print