Getlabs Webhooks

This guide will walk you through integrating and using webhooks with Getlabs to receive real-time updates and notifications about events in your account.

Introduction to Webhooks

Getlabs uses webhooks to notify you when an event happens in your account. Webhooks are useful for events like when an appointment is created for a patient or when a patient's appointment status is updated.

Setting Up Webhooks

1. Create a Webhook Endpoint

In order for Getlabs to communicate with your application you'll need to create an endpoint for our webhook service to communicate with.

Setting up a web application is outside the scope of this document but here are some important details on the specifics of the endpoint that we require from your endpoint:

• must be an https endpoint
• must be able to accept a POST call

2. Register Webhook Endpoint

Once you have an endpoint setup and configured on your server you can register that endpoint with us to start receiving events. Simply navigate to our Webhooks settings section to add an endpoint and register your webhook.

Once you've registered a webhook with us make sure you take note of the Signing Secret. This secret is used to verify that the request to your endpoint is, in fact, coming from us. More about how to verify webhook signatures can be found here.

NOTE: you'll need to have admin access to the Getlabs Portal to register a webhook.

Webhook Events

Events can be initiated/triggered in this Portal by you (the partner) or elsewhere by us in the Getlabs system. For example if a patient contacts us to book an appointment under your partner account an event would be sent out. Below are a list of webhook events that we currently have configured.

NOTE: For security and compliance with HIPAA we remove patient health information from our event payloads. If you need access to this information please use our Appointment endpoint to retrieve it.

Appointment Events

The following events correspond to lifecycle events with the appointment:

appointment.created

• Fired after an Appointment is created that is tied to your partner account in the Getlabs system.

appointment.updated

• Fired when an Appointment is updated in the Getlabs system.

NOTE: This event will get fired for all appointment updates. To help filter through the most used updated events we've created events that specifically handle status updates called Appointment Status Events

Appointment Status Events

Appointment Status Events are shortcuts to the appointment.update Appointment Event. If you only want to be notified of an appointment update when the status changes these events below can help:

appointment.cancelled

• Fired when an Appointment status is updated to Cancelled in the Getlabs system.

appointment.redraw

• Fired when a new appointment is created as a redraw appointment in the Getlabs system.

appointment.rescheduled

• Fired when an Appointment is rebooked in the Getlabs system.

appointment.specialist.running-late

• Fired when a specialist takes action and notifies a patient that they are running late for their scheduled appointment.

NOTE: This event is deprecated and will eventually be removed. Please listen to the appointment.notify-intent for the notificationType: SpecialistRunningLateNotification

appointment.in-progress

• Fired when an Appointment is in-progress in the Getlabs system.

appointment.completed

• Fired when an Appointment status is updated to Completed in the Getlabs system.

appointment.investigation.created

• Fired when an Appointment investigation is created.

appointment.notification-intent

• For partners that would like to intercept and handle appointment notifications, this event is fired when a notification is intended to be sent. The payload will contain an additional notificationType property
  
  While not an exhaustive list, the following are the most commonly used notification types that you can expect to receive in the payload:
  • AppointmentCancelledForPatientNotification
  • AppointmentCompletedNotification
  • AppointmentOneStopAwayNotification
  • AppointmentReminderNotification
  • AppointmentTimeChangeForPatientNotification
  • AppointmentTwoDaysBeforeReminderNotification
  • AppointmentTwoStopsAwayNotification
  • NewAppointmentForPatientNotification
  • SpecialistArrivedNotification
  • SpecialistEnRouteNotification
  • SpecialistRunningLateNotification

NOTE: Please ensure that you have informed us to disable default notifications before you start listening and taking action on these events. If not, patients will still receive notifications from us.

Appointment Request Events

An Appointment Request is a placeholder for a Getlabs Appointment. The details of the Appointment are obtained and we ask the Patient to select the time/day for us to visit them. Once an Appointment Request is Scheduled a Getlabs Appointment is officially Created.

appointment-request.created

• Fired after an Appointment Request is created that is tied to your partner account in the Getlabs system.

appointment-request.notification-intent

• For partners that would like to intercept and handle appointment request notifications, this event is fired when a notification is intended to be sent. The payload will contain an additional notificationType property
  
  While not an exhaustive list, the following are the most commonly used notification types that you can expect to receive in the payload:
  • AppointmentRequestedNotification
  • AppointmentRequestedReminderNotification

NOTE: Please ensure that you have informed us to disable default notifications before you start listening and taking action on these events. If not, patients will still receive notifications from us.

Appointment Request Status Events

Appointment Request Status Events are specific to status updates on the appointment request.

appointment-request.cancelled

• Fired when an Appointment Request status is updated to Cancelled.

appointment-request.scheduled

• Fired when an Appointment Request is scheduled and converted to an Appointment in the Getlabs system.

Webhook Payload Example:

Below is an example of what you can expect when receiving a payload:

{
  "id": "62168584-d449-47d5-bdce-9928c831081f",
  "eventType": "appointment.cancelled",
  "created": "2023-10-13T13:53:38.316Z",
  "data": {},
  "ref": "https://portal.getlabs.com/appointments/1f5f60de-7617-4d3c-b323-08e15f4145fe"
}

Payload Explained:

  id: The auditing identifier from our system.
  

  eventType: The audited event.
  

  created: Timestamp of when the event happened.
  

  data: The event payload data. ie: the appointment details.
  

  ref: A link to the affected record via portal.getlabs.com

The exact payload (located in the data param above) will return an object with the appointment details as per our API docs .

Verifying Webhook Signatures

To ensure the security and authenticity of webhook events, Getlabs uses a security feature called "Getlabs-Security." The Getlabs-Security is an HTTP header that is sent along with each webhook event, and it includes an HMAC-SHA256 (hex encoded) signature of the webhook payload. This signature is based on your Getlabs webhook signing secret, which is a unique key provided by Getlabs on each webhook that you register.

Here's how the Getlabs-Security security header works:

1. Generating a webhook signature (on the Getlabs side):
   • Getlabs generates a webhook payload, which is a JSON representation of the event data.
   • Getlabs computes an HMAC-SHA256 signature of the webhook payload using your webhook signing secret (provided by Getlabs) as the key.
   • The computed signature is added to the headers of the webhook event as the Getlabs-Security header.
2. Receiving and verifying the webhook signature (on your server):
   • When Getlabs sends a webhook event to your server, it includes the Getlabs-Security header.
   • Your server receives the webhook event and extracts the Getlabs-Security header value.
   • Your server also extracts the raw request body (the JSON payload) from the webhook event.
   • Using your webhook signing secret (provided by Getlabs), your server recomputes the HMAC-SHA256 signature of the request body.
   • Your server compares the computed signature with the value in the Getlabs-Security header.
   • If the two signatures match, it means the webhook event is authentic, and it can be trusted.
   • If the signatures don't match or the Getlabs-Security header is missing, your server should reject the event, as it might be a forged or altered request.

NOTE: The User-Agent header for each request Getlabs sends will contain 'getlabs-webhook'.

Webhook Response Codes

Your webhook must return a 200-ish (200-299) level http response code in a timely manner - under 30 seconds. Failure to do so will result in our system rejecting the webhook, thus initiating a retry.

Webhook Retry Mechanism

When we receive a NON 200-ish response your webhook message will be retried at a later time. Getlabs Webhooks will retry again after a minimum backoff period of 100 seconds, exponentially increasing up to 600 seconds. Getlabs will retry failed messages for up to 24 hours.

If the message still cannot be delivered after the maximum number of retries, Getlabs Webhooks may consider the message as undeliverable.

In the case of prolonged downtime of your application we might send multiple requests. Our retry mechanism is not ordered. An application that implements Getlabs Webhooks should be idempotent.

API Reference

Our data payloads mirror our API responses, minus any PHI - for security reasons. Please see details from our API Documentation website .