Webhook functionality enables clients to receive information about when certain events happen in the system. For example, a client can choose to get a notification whenever a patient survey is completed.
To start using webhooks, you’ll need to register a proper configuration - one that defines which events you are interested in and which endpoint we should send information about that event to.
Once the configuration is registered, the url you provided will start receiving POST requests using a specific payload every time that event is triggered.
The webhook request will always be sent as an HTTP POST
, therefore you need to guarantee that the endpoint URL you provide is able to
accept such requests.
For authentication, each request will contain a x-webhook-infermedica-token
header, which will use the token you provided when registering your
webhook configuration. Use this token to verify that the request comes from Infermedica API, not a malicious actor.
Each request body will use the following format:
{
"event_type": str,
"content": dict
}
Both the available values for event_type
and the types of returned content
are available in the next section.
List of currently available webhook events that you can subscribe to:
Event name | Description | Content |
survey_finished | Event triggered when a patient finishes the Intake survey. In other words, when the survey status changes to completed . |
|
To start receiving webhook requests, you first need to register your configuration:
curl --location --request POST 'https://<INSTANCE_URL>/api/v2/config/webhook' \
--header 'Authorization: Bearer <CREDENTIALS>' \
--header 'Content-Type: application/json' \
--data-raw '{
"url": "https://mywebsite.com/webhook_receiver",
"authorization_token": "zGORr7q1I4egIr0c0eKXD7CMpIcjFooJ",
"subscribed_events": ["survey_created"]
}'
In the response you will receive the data that you provided, along with the ID of the registered configuration:
{
"id": "12345678-1234-5678-1234-567812345678",
"url": "https://mywebsite.com/webhook_receiver",
"authorization_token": "zGORr7q1I4egIr0c0eKXD7CMpIcjFooJ",
"subscribed_events": ["survey_created"],
}
URL that the webhooks will be sent to, as per the configuration set. Must be capable of accepting POST
requests.
Authorization token that will be used by the API to authenticate to the provided URL. Token will be send as a part of each webhook request, in the
x-webhook-infermedica-token
header.
Event types that will be listened for and for which webhooks will be sent. For a list of available events, see the Event types section.
To update non-token data, use:
curl --location --request PATCH 'https://<INSTANCE_URL>/api/v2/config/webhook/{id}' \
--header 'Authorization: Bearer <CREDENTIALS>' \
--header 'Content-Type: application/json' \
--data-raw '{
"url": "https://mywebsite.com/webhook_receiver",
"subscribed_events": ["survey_created"]
}'
In the response you will receive the updated webhook data, with the token omitted:
{
"id": "12345678-1234-5678-1234-567812345678",
"url": "https://mywebsite.com/webhook_receiver",
"subscribed_events": ["survey_created"]
}
Webhook configuration ID.
URL that the webhooks will be sent to, as per the configuration set. Must be capable of accepting POST
requests.
Event types that will be listened for and for which webhooks will be sent. For a list of available events, see the Event types section.
To update the token, use:
curl --location --request PATCH 'https://<INSTANCE_URL>/api/v2/config/webhook/{id}' \
--header 'Authorization: Bearer <CREDENTIALS>' \
--header 'Content-Type: application/json' \
--data-raw '{
"authorization_token": "zGORr7q1I4egIr0c0eKXD7CMpIcjFooJ",
}'
In the response you will receive the updated webhook data, including the updated token:
{
"id": "12345678-1234-5678-1234-567812345678",
"url": "https://mywebsite.com/webhook_receiver",
"subscribed_events": ["survey_created"],
"authorization_token": "zGORr7q1I4egIr0c0eKXD7CMpIcjFooJ"
}
Webhook configuration ID.
Authorization token that will be used by the API to authenticate to the provided URL. Token will be send as part of each webhook request, in the
x-webhook-infermedica-token
header.
To get all of the webhook configurations that belong to the current client, use:
curl --location --request GET 'https://<INSTANCE_URL>/api/v2/config/webhook' \
--header 'Authorization: Bearer <CREDENTIALS>' \
--header 'Content-Type: application/json'
In the response you will receive an array of all of the registered configurations, tokens excluded:
[{
"id": "12345678-1234-5678-1234-567812345678",
"url": "https://mywebsite.com/webhook_receiver",
"subscribed_events": ["survey_created"],
}]
To get a specific webhook configuration, use:
curl --location --request GET 'https://<INSTANCE_URL>/api/v2/config/webhook/{id}' \
--header 'Authorization: Bearer <CREDENTIALS>' \
--header 'Content-Type: application/json'
In the response you will receive the webhook data requested, token excluded:
{
"id": "12345678-1234-5678-1234-567812345678",
"url": "https://mywebsite.com/webhook_receiver",
"subscribed_events": ["survey_created"],
}
Webhook configuration ID.
To delete a webhook configuration, use:
curl --location --request DELETE 'https://<INSTANCE_URL>/api/v2/config/webhook/{id}' \
--header 'Authorization: Bearer <CREDENTIALS>' \
--header 'Content-Type: application/json'
In the response you will receive the deleted webhook data, token excluded:
{
"id": "12345678-1234-5678-1234-567812345678",
"url": "https://mywebsite.com/webhook_receiver",
"subscribed_events": ["survey_created"],
}
Webhook configuration ID.