Receive data as soon as it becomes available.
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:
General requirements for the endpoint:
POST
HTTP request;x-metriport-signature
- see authentication below;200
in under 4 seconds - we recommend processing the webhook request asynchronously;ping
message;Additionally, your endpoint will need to accept and process different messages when they become available - specifically:
When Metriport sends a webhook message, it includes an x-metriport-signature
header - this is an
HMAC SHA-256 hash computed using your webhook key and the body of the webhook message.
At a high level, an HMAC works by taking a secret key (webhook key from the Settings page) and a message, and performing iterative hashes of the two to create a signature. That signature is compared against the signature in the header for equality. If the signatures are equal, you can trust the webhook payload is authentic and has not been tampered with. If they aren’t equal, you should throw it away.
You can use this header to verify that the webhook messages sent to your endpoint are from Metriport.
Avoid parsing the request body before generating the signature - it could result in a slightly different signature that’s enough to invalidate it.
Here’s an example of how you can do this in Node.js - see the full sample code here:
The important thing is to make sure you use a trusted cryptography library in whatever language you choose to validate the webhook message in.
You can also validate the HMAC in Python - see the full sample code here:
If using the dashboard: simply delete your webhook URL on the Developers page, save, and enter it again.
If using the API: set the webhook URL to an empty string via the Update Settings endpoint, and then set it to your desired URL making another request to the same endpoint.
Webhook requests contain the relevant information on the body of the HTTP request.
There are several types of messages you can expect to receive:
ping
: validation of the webhook connection between Metriport and your app;In general, 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.
ping
messageThis is a simple message to validate access to your app’s webhook endpoint. Your app should
accept a POST
request with this body…
…and respond to this request by sending back the <random-sequence>
as below:
You can check the webhook mock server available on our repository for a simple implementation of this message.
When using the Medical API, Metriport will send Webhook messages containing status updates to your app, as soon as the data becomes available.
You can see Webhook details specific to the Medical API, including which operations trigger Webhook messages, on this page.
Webhook updates will contain meta information.
Example payload:
The format follows:
Metadata about the message.
Sometimes, due to temporary network disruption (or whatever other reason), a Webhook payload may fail to be delivered to your app. In these cases, Metriport will store the failed requests, and you can then manually retry them - using either the dashboard, or the API.
If you do not have the Webhook URL configured, the Metriport will not attempt to deliver Webhook messages for the Medical API - in which case retries are not applicable.
On the Developers page in the dashboard, you’re able to see the count of Webhook requests currently processing, and a count of outstanding ones that failed:
To retry failed requests, simply click the Retry
button, and those requests will be sent to your app again.
Currently, the Metriport API doesn’t implement automatic retries - let us know if this is something you need.