Webhooks

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.

Webhook request details

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": "...",
  "content": {
    ...
  }
}

Both the available values for event_type and the types of returned content are available in the next section.

Event types

List of currently available webhook events that you can subscribe to:

Event name: survey_finished

Description: Event triggered when a patient finishes the Intake survey. In other words, when the survey status changes to completed.

Content:

{
  "survey_id": "..."
}

Creating a webhook configuration

To start receiving webhook requests, you first need to register your configuration:

curl 'https://<INSTANCE_URL>/api/v2/config/webhook' \
  -X 'POST' -L \
  -H 'Authorization: Bearer <CREDENTIALS>' \
  -H 'Content-Type: application/json' \
  -d '{
     "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"]
}

Request parameters in body

url (str, required)

URL that the webhooks will be sent to, as per the configuration set. Must be capable of accepting POST requests.

authorization_token (str, required)

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.

subscribed_events (list[str], optional)

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.

Updating a webhook configuration

To update non-token data, use:

curl 'https://<INSTANCE_URL>/api/v2/config/webhook/{id}' \
  -X 'PATCH' -L \
  -H 'Authorization: Bearer <CREDENTIALS>' \
  -H 'Content-Type: application/json' \
  -d '{
     "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"]
}

Path parameters

id (str)

Webhook configuration ID.

Request parameters in body

url (str, optional)

URL that the webhooks will be sent to, as per the configuration set. Must be capable of accepting POST requests.

subscribed_events (list[str], optional)

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.

Updating the webhook token configuration

To update the token, use:

curl 'https://<INSTANCE_URL>/api/v2/config/webhook/{id}' \
  -X 'PATCH' -L \
  -H 'Authorization: Bearer <CREDENTIALS>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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"
}

Path parameters

id (str)

Webhook configuration ID.

Request parameters in body

authorization_token (str, required)

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.

Getting all of the webhook configurations

To get all of the webhook configurations that belong to the current client, use:

curl 'https://<INSTANCE_URL>/api/v2/config/webhook' \
  -X 'GET' -L \
  -H 'Authorization: Bearer <CREDENTIALS>' \
  -H '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"]
  }
]

Getting a specific webhook configuration

To get a specific webhook configuration, use:

curl 'https://<INSTANCE_URL>/api/v2/config/webhook/{id}' \
  -X 'GET' -L \
  -H 'Authorization: Bearer <CREDENTIALS>' \
  -H '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"]
}

Path parameters

id (str)

Webhook configuration ID.

Deleting a webhook configuration

To delete a webhook configuration, use:

curl 'https://<INSTANCE_URL>/api/v2/config/webhook/{id}' \
  -X 'DELETE' -L \
  -H 'Authorization: Bearer <CREDENTIALS>' \
  -H '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"]
}

Path parameters

id (str)

Webhook configuration ID.