Using webhooks

Introduction

Upheal utilizes webhooks to keep you informed about events occurring on the Upheal platform. Webhooks serve as a means for us to send you notifications when significant session processing events occur or when a user is created. When you register a webhook with us, we will send an HTTP POST request to the URL you provide.

Webhook endpoint requirements

To receive webhooks, you must specify a single endpoint URL for each environment. For both development and production environments, you will need to register two separate endpoint URLs. These URLs must meet the following requirements:

1. Security: The endpoint URL must be publicly accessible via HTTPS and support TLSv1.2+ encryption. It should also have a valid certificate chain issued by a trusted Certificate Authority (CA).
2. HTTP POST: The endpoint URL must be capable of accepting HTTP POST requests.
3. Response: It should be able to respond with either a 200 or 204 HTTP Status Code.
4. Timeout: The endpoint URL must respond within 5 seconds to the webhook request.

In case of a webhook failure, we will retry the request up to 5 times with an exponential backoff delay.

Webhook headers

The request will contain the following headers:

• x-upheal-signature: A signature of the request body. See Signature verification for more details.
• x-upheal-timestamp: The timestamp of the request in milliseconds since the Unix epoch.
• Content-Type: The content type of the request body. Will always be application/json.
• Content-Length: The length of the request body in bytes.
• User-Agent: The user agent of the request. Will always be Upheal Webhook.

Webhook events

The request body will contain the details of the event that occurred. The events are different for Processing API and Application API.

1. Processing API events

Processing Session Events

For every processing event, we send a webhook when processing is finished. You can follow up by calling the Get processing session information endpoint.

The request will contain eventType and payload with processing id.

Example:

{
  "eventType": "PROCESSING_SESSION_FINISHED",
  "payload": {
    "processingId": "8b80884195dc0a810195eb8bc53e0023"
  }
}

Compliance Job Events

Upheal will trigger this event when a compliance job has finished processing.

• eventType: COMPLIANCE_JOB_COMPLETED
  • Indicates that the job completed successfully.
  • The payload includes the job ID and detailed results for each submitted file or input.
• eventType: COMPLIANCE_JOB_FAILED
  • Indicates that the job failed to complete successfully (e.g. due to processing errors).
  • The payload structure is the same as in the completed event, allowing you to inspect partial or failed evaluations.

Each event contains a payload with jobId that you can use to query the job results.

Example webhook payload:

{
  "eventType": "COMPLIANCE_JOB_COMPLETED",
  "payload": {
    "jobId": "job-123",
  }
}

Smart Edit Job Events

Upheal will trigger this event when a smart edit job has finished processing.

• eventType: SMART_EDIT_JOB_COMPLETED
  • Indicates that the smart edit job completed successfully.
  • The payload includes the job ID that you can use to retrieve the final results.
• eventType: SMART_EDIT_JOB_FAILED
  • Indicates that the smart edit job failed to complete successfully (e.g. due to processing errors or invalid input).
  • The payload structure is the same as in the completed event.

Each event contains a payload with jobId that you can use to query the job results.

Example webhook payload:

{
  "eventType": "SMART_EDIT_JOB_COMPLETED",
  "payload": {
    "jobId": "ec40b282-8cf3-4659-9976-50d411203c2f"
  }
}

Possible event types are:

• PROCESSING_SESSION_FINISHED - called when processing is finished and all insights are available
• PROCESSING_SESSION_NOTES_FINISHED - called when notes are available
• COMPLIANCE_JOB_COMPLETED - called when a compliance job completes successfully
• COMPLIANCE_JOB_FAILED - called when a compliance job fails
• SMART_EDIT_JOB_COMPLETED - called when a smart edit job completes successfully
• SMART_EDIT_JOB_FAILED - called when a smart edit job fails

2. Application API events

Application API events reflect interactions with the Application API and with the Upheal Web Application. There are two types of events:

Session events

You get notifications for all sessions created inside your organization whenever any of the following events occur:

1. The creation of a new session.
2. The commencement of session processing.
3. The completion of session note processing. This is faster compared to the completion of the entire session processing.
4. The completion of session processing (including analytics).
5. The termination of session processing due to an error.

The request will be a JSON object with the following fields:

• eventType: The type of event that occurred. Possible values are:
  • SESSION_CREATED
  • SESSION_PROCESSING_STARTED
  • SESSION_PROCESSING_NOTES_COMPLETED
  • SESSION_PROCESSING_COMPLETED
  • SESSION_PROCESSING_FAILED
• sessionId: The ID of the session that was created or processed.
• providerUserId: The ID of the user registered in your system to whom the session relates.
• partnerAppointmentId: Optional id provided when initiating session.

Example request payload:

{
  "sessionId": "4ce9b293-911f-4803-b311-85178c812a4c",
  "eventType": "SESSION_CREATED",
  "providerUserId": "2b11f387-a35d-4dbd-b338-222a93ed5b97",
  "partnerAppointmentId": "869ec0f7-8c76-4981-a7c5-b74721c7bdd0"
}

User events

You get notifications whenever a user is created in your organization via the Upheal application.

The request will be a JSON object with the following structure:

• eventType: The type of event that occured. The only possible value is: USER_CREATED
• payload:
  • userId: id of the created user
  • externalUserId: optional external id provided via integration API
  • role: role of the user, possible values are:
    • Client
    • HealthcareProvider
    • OrgAdmin

Example request payload:

{
  "eventType": "USER_CREATED",
  "payload": {
    "userId": "2b11f387-a35d-4dbd-b338-222a93ed5b97",
    "externalUserId": "123456789,
    "role": "HealthcareProvider"
  }
}

Registering a webhook

Upon your registration with Upheal you will receive a pair of keys.

• API key: Used for making calls to our Integration API.
• Webhook secret: Used for verifying the authenticity of webhook requests.

Please store these keys securely. You will need the Webhook secret to validate each incoming webhook request. See Signature verification for more details.

Signature verification

To verify the authenticity of a webhook request, you must compute a signature of the request body using the Webhook secret.

Here is a step-by-step guide on how to do this.

Step 1: Collect the required information

1. Receive the webhook request.
2. Retrieve the x-upheal-signature header from the request.
3. Retrieve the x-upheal-timestamp header from the request.
4. Retrieve the request body.

Step 2: Compute the signature

After receiving a webhook request, construct the message string with v0, the webhook request header x-upheal-timestamp value, and the webhook request body. Separate each section with a colon :. For example:

v0:{Value of x-upheal-timestamp}:{Webhook request body as string}

Step 3: Hash the message

Use the HMAC SHA256 algorithm to compute the message digest for the message string using your Webhook secret as the key. For example, in Node.js:

const crypto = require('crypto')

const message = `v0:${request.headers['x-upheal-timestamp']}:${JSON.stringify(request.body)}`

const signature = crypto.createHmac('sha256', UPHEAL_WEBHOOK_SECRET_TOKEN).update(message).digest('hex')

if (request.headers['x-upheal-signature'] === signature) {
  // Webhook request came from Upheal and it's safe to process
} else {
  // Webhook request did not come from Upheal. Ignore it.
}
...