Webhooks

​

Overview

Usually, when an application wants to consume information from another it makes a request to obtain such information.

Webhooks turn this around: the producer of information calls the consumer when data is available. This way, the consumer doesn’t have to poll the producer regularly to obtain information.

Metriport will call your app’s webhook endpoint when user data is available - there’s no way for your application to request data exposed through webhooks.

To enable this integration approach with Metriport:

1. Expose a public endpoint on your app;
2. Set this endpoint URL on the Developers page in the developer dashboard;
3. This will generate a webhook key that should be used to authenticate requests on your app’s endpoint (webhook).

General requirements for the endpoint:

1. Public endpoint accessible from the internet;
2. Accepts a POST HTTP request;
3. Verifies requests by comparing the HTTP header x-webhook-key with the webhook key;
4. Accepts and responds to a ping message;
5. Accepts and processes user data messages.

​

Authentication

Validate requests to your public endpoint by comparing the webhook key with each request’s HTTP header.

The webhook key is accessible on Developers page in the developer dashboard - see how to enable webhooks on the overview section.

The HTTP header will contain a header named x-webhook-key - it should contain the webhook key above. Your app is expected to disregard requests if those don’t match. We suggest returning a HTTP status code 401 with no body in such cases.

If you want to generate a new webhook key, delete your webhook URL on the Developers page, save, and enter it again.

​

Format

Webhook requests contain the relevant information on the body of the HTTP request.

There are two types of messages:

• ping: validation of the webhook connection between Metriport and your app;
• user data: health information grouped by user.

​

The ping message

This is a simple message to validate access to your app’s webhook endpoint. Your app should accept a POST request with this body…

{
  "ping": "<random-sequence>"
}

…and respond to this request by sending back the <random-sequence> as below:

{
  "pong": "<random-sequence>"
}

You can check the webhook mock server available on our repository for a simple implementation of this message.

​

User data message

These are the messages Metriport will send to your app with user data from Providers, as soon as those become available.

The format follows:

{
  "meta": {
    "messageId": "<message-id>",
    "when": "<date-time-in-utc>"
  },
  "users": [
    {
      "userId": "<user-id-1>",
      "sleep": [
        {
          "metadata": {
            "date": "2022-12-21",
            "source": "garmin"
          },
          "start_time": "2022-12-12T22:15:40Z",
          "end_time": "2022-12-13T04:15:40Z",
          "durations": {
            "awake_seconds": 400,
            ...
          },
          "biometrics": {
            "heart_rate": {
              "avg_bpm": 70,
              ...
            },
            ...
          }
        },
        {
          "metadata": {
            "date": "2022-12-21",
            "source": "garmin"
          },
          "start_time": "2022-12-12T22:15:40Z",
          "end_time": "2022-12-13T04:15:40Z",
          "durations": {
            "awake_seconds": 400,
            ...
          },
          "biometrics": {
            "heart_rate": {
              "avg_bpm": 70,
              ...
            },
            ...
          }
        }
      ],
      "activity": [
        {
          "metadata": {
            "date": "2022-12-21",
            "source": "garmin"
          },
          "summary": {
            "biometrics": {
              ...
            },
            "durations": {
              ...
            },
            ...
          },
          "activity_logs": [
            ...
          ],
        }
      ]
    },
    {
      "userId": "<user-id-2>",
      ...
    }
  ]
}

Upon successful receiving of these messages, it’s expected that your app responds with a 200 HTTP status code (OK).

There’s no need to include anything on the response body.