Awell Health Developer Hub
Developer Hub
Back-end:

This integration enables you to orchestrate activities over time for multiple stakeholders on an Awell Hosted Activity page.

This use case is perfect to set up longitudinal outcomes (such as PROMs / PREMs) collection, triage & eligibility flows and clinicial decision support with limited engineering effort.

Hosted activity lifecycle

The lifecycle for a hosted activity experience looks like this:

  1. At some point in time, a patient is created and included in a care pathway.
  2. When an activity is created (activated) in the pathway, your system will get notified via the activity.created webhook.
  3. At that point in time, you know something in the pathway needs to be completed by a given stakeholder. You can notifiy that stakeholder via the appropriate channels.
  4. The stakeholder reacts to the notification and wants to complete the activity. This is the trigger to create a Hosted Activity Session via the Awell API.
  5. Our API creates a Hosted Activity Session scoped for that stakeholder where you can redirect the stakeholder to in order to complete the pending activity. Note that a Hosted Activity Session is always scoped per stakeholder.
  6. The stakeholder can complete the activity and we will let you know when the activity is completed via the activity.completed webhook.

This lifecycle is repeated for every activity that is created in a care pathway.

Hosted activity sequence diagram
Hosted activity lifecycle © Awell Health

Prerequisites

To get started, there are a couple of things you need:

  1. An API key to authorize requests to the Awell API. Click here to get your API key.
  2. A patient resource created and included in a care pathway. It is not explicitly part of this guide but you can find documentation on creating a patient and starting a pathway on the respective links.
  3. Webhooks set up for your care pathway (see below).
  4. You have a server that can listen to incoming wehooks and perform an action based on the events (eg: notifiy the stakeholder).

Webhooks

Your pathway should minimally be subscribed to the activity.created webhook as that is the trigger to initiate a Hosted Activity session. Depending on the type of integration and events you want to receive, you can configure other wehooks as well ( see list of all webhooks).

Webhooks are configured on a per pathway basis via the pathway settings so if you want to receive webhooks for events, you will have to configure them via the pathway settings.

Configure webhooks

Click here for more information on how to configure Webhooks on pathways. The payload of the activity.created webhook can be found on the respective link.

Get started

1
Create Webhook listener and notify stakeholders

We will create a Webhook listener that is able to process and handle incoming webhooks from Awell every time an activity is created.

Interactive webhook builder

Use our interactive webhook builder to quickly generate code to process & handle webhooks coming from Awell

Handle the event

Handle the activity.created event on your server.

Only handle user activities

Care flows/pathways in Awell consist of different types of activities. We are only interested in activities that need an action by a human.

Store pathway id and stakeholder id

In order to create a Hosted activity session, you will need to pass the pathway id and stakeholder id. So make sure you store or pass these 2 properties.

Resources:

Notify the stakeholders

Depending for what stakeholder there is an activity to complete, define and call the methods to notify these stakeholders via your appropriate channels.

  • server.js
01const express = require('express');
02const app = express();
03

04// If you are using Express v4 - v4.16 you need to use body-parser, not express, to retrieve the request body
05app.post('/awell-webhooks', express.json({type: 'application/json'}), (request, response) => {
06  const event = request.body;
07

08  // Handle the event
09  switch (event.event_type) {
10    case 'activity.created': {
11      const { isUserActivity } = event.activity
12      
13      if (isUserActivity) {
14        const pathway_id = event.pathway.id
15        const { stakeholder } = event.activity.indirect_object
16        const stakeholderId = stakeholder.id
17

18        if (stakeholder.type === 'PATIENT') {
19          // Email is only available if this property is set in the patient's Awell profile
20          // Contact details can also be fetched from your internal systems.
21          const patientEmail = stakeholder.email
22

23          // Then define and call a method to notify the patient
24        }
25        if (stakeholder.type === 'STAKEHOLDER') {
26          switch (stakeholder.name) {
27            case 'Nurse': {
28              // Then define and call a method to notify the nurse of the patient
29              break
30            }
31            case 'Physician': {
32              // Then define and call a method to notify the physician of the patient
33              break
34            }
35            default:
36              console.log(`Unhandled stakeholder: ${stakeholder.name}`)
37          }
38        }
39      }
40      break;
41    }
42    default:
43      console.log(`Unhandled event type ${event.event_type}`);
44  }
45

46  // Return a response to acknowledge receipt of the event
47  response.json({received: true});
48});
49

50app.listen(8000, () => console.log('Running on port 8000'));

Table to help you map user activities to the right stakeholder:

Stakeholder type
(indirect_object.type)		Stakeholder name
(indirect_object.name)		Contact details of stakeholder
PATIENTName of the actual patient as stored in the Awell patient profileSee stakeholder.email (if contact details are stored in Awell) or look up in your internal systems.
STAKEHOLDERnurseLook up in your internal systems.
STAKEHOLDERPhysicianLook up in your internal systems.
STAKEHOLDERDieticianLook up in your internal systems.
STAKEHOLDER(any other stakeholder that is not the patient)Look up in your internal systems.
2
Start hosted activity session

In the previous step we created a webhook listener and notified the relevant stakeholders of an activity that needs to be completed. When the stakeholder react to the notification (eg: presses a button), we will create a hosted activity session we can redirect the stakeholder to.

Prerequisites
You will need to have stored or passed (eg: via query parameters) the following data in order to start a hosted activity session (see step 1):

  1. Stakeholder id
  2. Pathway id

Configure variables

Give the variables and appropriate values.

Resources:

Get stakeholder and pathway id

Make sure you have the id of the stakeholder the activity is for and the pathway id. These parameters were returned in the body of the webhook. In the example we passed them via query parameters.

Define success and cancel URL

Specifiy where the stakeholder needs to be redirected to when the session is completed or interrupted.

Start a session

Create a session via the Awell API.

Resources:

Redirect to Hosted Pathway page

After creating the session, redirect your client to the URL for the hosted pathway page returned in the response.

  • server.js
01const express = require('express');
02const app = express();
03

04const AWELL_API_URL = process.env.AWELL_API_URL || ''
05const AWELL_API_KEY = process.env.AWELL_API_KEY || ''
06

07// If you are using Express v4 - v4.16 you need to use body-parser, not express, to retrieve the request body
08app.post('/start-hosted-activity-session', express.json({type: 'application/json'}), (request, response) => {
09  // Assumption: these parameters are passed as query parameters
10  // Replace this code if you have implemented a different way
11  // to keep track of stakeholder and pathway id.
12  const STAKEHOLDER_ID = req.query.stakeholder_id
13  const PATHWAY_ID = req.query.pathway_id
14

15  const body = JSON.stringify({
16    query: `
17    mutation StartHostedActivitySession($input: StartHostedActivitySessionInput!) {
18      startHostedActivitySession(input: $input) {
19        session_id
20        session_url
21      }
22    }`,
23    variables: {
24      input: {
25        pathway_id: PATHWAY_ID,
26        stakeholder_id: STAKEHOLDER_ID,
27        success_url: 'https://your-domain.com/?success=true',
28        cancel_url: 'https://your-domain.com/?canceled=true',
29      },
30    },
31  })
32

33  const session = await fetch(AWELL_API_URL, {
34    method: 'POST',
35    headers: {
36      apiKey: AWELL_API_KEY,
37      Accept: 'application/json',
38      'Content-Type': 'application/json',
39    },
40    body,
41  })
42    .then((response) => response.json())
43    .then((response) => response.data.startHostedActivitySession)
44

45  res.redirect(303, session.session_url)
46});
47

48app.listen(8000, () => console.log('Running on port 8000'));
3
Test your set-up

In order to test your integration, make sure to do the following steps:

  1. Make sure your pathway has webhooks configured and they are sent to your server responsible for handling them. More on testing webhooks can be found [here](/awell-orchestration/developer-tools/webhooks/test-webhooks).
  2. Make sure your pathway is published.
  3. Make sure your server(s) are up and running.
  4. Enroll a patient in your pathway.
  5. Your server should be receiving webhooks now and you should be able to test your integration end-2-end.

Frequently asked questions

If you can't find what you're looking for, you can always send us a message over Intercom with your enquiry.