Connect Forms API Notifications to Your Custom Notification Service ​

You can connect your own notification service to the Forms API notifications service. What this means is suppose you already have created an in-house service to send PROMs reminders to your patients, you can leverage the Forms API to store your PROMs forms as well as utilize its notifications service. You can provide a callback URL in your form assignment in lieu of a phone number or email address. We will then send a request to your URL via webhook that let's your service know which form is ready to remind a patient to complete

Register Your Callback URL ​

To register your callback URL in your form assignment set your communication method as below:

// form assignment
{
  ...other form assignment attributes,
  communicationMethod: {
    type: 'callback',
    callbackUrl: 'https://your-callback.com/deindentified-id'
  }
}

Important: We suggest providing an identifier, make sure this is privacy compliant (ex: HIPAA-compliant), as a path parameter so your notification service is aware of which patient needs a reminder sent to.

Webhook Request Body ​

The Forms API notification service will send your webhook a request when an assignment is in the active window (the current date is between the startDate and endDate) and based on your tenant's reminder configuration notifcation frequency (reminderInterval). Below you can see the request body from the API's webhook. Importantly, you will receive the formId as well as the patient (deidentified ID from your URL), so that your custom notification solution is aware of what form and to whom a reminder needs sent.

{
  "id": "4ca3abe5-d448-4590-be4d-8f5901398caf",
  "tenantId": "1",
  "formId": "bf484e43-bdc0-4cdd-859b-a9505f025adc",
  "revisionId": "2eceef09-e867-4111-81a8-543841fac543",
  "correlationTag": "DEIDENTIFIED-ID-0001",
  "startDate": "2023-12-01T00:00:00.000Z",
  "endDate": "2023-12-08T00:00:00.000Z",
  "createdOn": "2023-12-04T14:23:22.729Z",
  "updatedOn": "2023-12-04T14:23:22.729Z",
  "communicationMethodType": "callback",
  "communicationMethodValue": "https://your-callback.com/deindentified-id"
}

Securing your Webhook ​

Forms API can generate for you a public and private key pair using the Edwards-curve Digital Signature Algorithm (EdDSA). If you would like to set up a webhook for connecting the Forms API notifications service to your custom notification service, you may create and retrieve your public key to verify webhook request header signatures. The Forms API will retain your private key for signing requests to be sent to your notification service. We will discuss the process in the next section, Public Key & Verification.