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.

1
curl -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
}'

1
{
2
  "type": "order.status",
3
  "url": "https://impilo.health",
4
  "id": 123
5
}

Webhook Types

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.

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:

1
curl -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:

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:

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

Webhook logs 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.

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.

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

$
curl -X POST http://localhost:8000/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.

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.