Webhook

A webhook listens for specific events and will send an HTTP request when the event occurs.

List of events

• account_link
• activity_create
• activity_delete
• activity_update
• activity_transition_scheduled
• activity_transition_expired
• activity_reminder
• appointment_create
• appointment_update
• article_create
• careplan_create
• careplan_delete
• careplan_update
• careplan_definition_create
• careplan_definition_delete
• careplan_definition_update
• encounter_create
• encounter_update
• member_create
• member_delete
• member_update
• questionnaire_create
• questionnaire_update
• questionnaire_response_create
• questionnaire_response_update
• schedule_create
• schedule_update

Strategies

When registering a webhook, you can provide a strategy to use. Typically webhooks will use the after strategy. This is also the default if a strategy is not provided. Below is an overview of the different options:

after - (default) The operation runs first and the request body will contain the output of the operation. handle - Runs instead of the operation. Undefined behaviour if this strategy is used by multiple webhooks. before - (unstable) Runs before the operation.

Example:

POST /webhook

{
  "configurationId": 123,
  "url": "//endpoint/account_link",
  "triggers": [{ "strategy": "handle", "event": "account_link" }],
  "display": "Custom account linking",
}

Integration webhooks

If a webhook is linked to an integration (using configurationId), it exposes the integration.endpointUrl by prefixing the webhook url with //endpoint.

Example:

POST /webhook

{
  "configurationId": 123,
  "url": "//endpoint/reload-activities",
  "triggers": [{ "strategy": "after", "event": "activity_create" }],
  "display": "Do something",
}

Account linking

First register a webhook to handle account linking:

POST /webhook

{
  "configurationId": 123,
  "url": "//endpoint/account_link",
  "triggers": [{ "event": "account_link" }],
  "display": "Custom account linking for Example",
}

The webhook will contain several parameters that can influence the account linking process. Here is an example webhook request body:

{
  "event": "account_link",
  "params": {
    "sub": "example",
    "providerId": 123,
    "userinfo": {
      "sub": "example",
      "name": "Example Person",
      "ssin": "99123100000"
    },
    "mapping": {
      "name": "name",
      "nationalId": "ssin"
    },
    "mapped": {
      "name": "Example Person",
      "nationalId": "99123100000"
    }
  },
  "projectId": 123
}

Based on this information, your integration should respond with either the memberId or the userId that this account belongs to:

{ "memberId": 123 }

{ "userId": 123 }

That's it!

activity_transition_scheduled

This webhook is called when an activity.activateAt has passed and its status is proposed.

The default behaviour is to update the activity status to scheduled. Use the handle strategy to override this default.

request.body.params: { id, transitionId, activity, status: "scheduled" }

activity_transition_expired

This webhook is called when an activity.endAt has passed and its status is proposed or scheduled.

The default behaviour is to update the activity status to expired. Use the handle strategy to override this default.

request.body.params: { id, transitionId, activity, status: "expired" }

activity_reminder

This webhook is called when an activity.remindAt has passed and its status is scheduled.

The default behaviour to set reminderAt to null and create a notification with title ${type}: ${display}. If actorType is not "subject", the notification is not sent. Use the handle strategy to override this default.

{ id, transitionId, activity,
  reminder: {
    offset: number
    offsetUnit: 's' | 'min' | 'h' | 'd' | 'wk' | 'mo' | 'a'
    topic?: string
    /** Options: email, sms, firebase, expo */
    medium?: string | string[]
    title?: string
    body?: string
  }
}