Webhooks

Introduction

Webhooks are a solution for triggering actions, updates and automations in other systems based on certain events happening in the Ally platform. It is an efficient way to integrate our system with your own as you do not need to keep polling our REST API for updates.

Required role

Webhook creation and management is available to the following roles on the system:

Administrator
Developer

To see your role, click the initals in the top right corner of the dashboard.

Test Mode

Webhooks are supported in Test Mode. You can try out webhooks and create webhooks in Test Mode that will not use or affect production data. We suggest that you point Test Mode webhooks to your development or staging systems and try out changes to your configuration there before copying the config (and updating endoints) for your live systems by disabling Test Mode and creating and updating webhooks.

Creating and managing webhooks

Step-by-step-guide

Step	Notes
Disable or enable Test Mode	Select depending if you want the webhook to operate on live or test data
Navigate to webhooks	Select the cog icon in the top right corder, and select Webhooks from the menu sidebar
Click "Add webhook"	- Payload URL is the URL that you want the payload data sent to - At this time we support JSON payloads - Choose which events you would like to receive a webook for
Click "Add webhook"
Make a note of the webhook secret	The webhook secret can be used to authenticate that the payload you receive originated from our system. See Authentication.

Authentication

Our webhook service supports HMAC to enable you to verify that webhooks received at your system are genuine. Use the secret generated when the webhook was created to decrypt the HMAC signature in the request header. HMAC is a useful protocol as it verifies that the payload has not been modified.

If you need to view the secret again, or regenerate the secret after a period of time please delete the existing webhook and re-create it.

Supported events

The following events are supported:

appointment.created
appointment.scheduled
appointment.completed
appointment.cancelled
appointment.updated

To understand what these events mean and when they are triggered please refer to Events Overview. If you wish to receive an event that is not in the current supported event list please contact Ally support.

Payload

The payload that is sent in the wehbook relates to the entity referenced in the event. For an appointment.x event, then the appointment object is sent.

All payloads are sent in JSON format and the entity is wrapped in a "data" property such as:

{
  "data": {
    "id": "apt_9HRUhuDrE9x882Tgx2",
    "createdAt": "2023-10-13T09:53:45.552Z",
    "updatedAt": "2023-10-13T09:53:45.552Z",
    "status": "scheduled",
    "phoneNumber": "+44777711111",
    "note": "These are my appointment notes",
    "completionNotes": null,
    "externalRef": "MYREF123",
    "patient": {
      "id": "p_Nalv9kl3lT0g8wGlC1"
    },
    "task": {
      "id": "tsk_LMHYyxJ9TNehdKhcaz"
    },
    "window": {
      "id": "win_OxhmNYLO74r6988yom"
    },
    "practitioner": {
      "id": "pr_Edzpwwr2f1idMFpfBb5"
    },
    "location": {
      "line1": "25 Bladnoch",
      "line2": "Wigtown",
      "city": "Newton Stewart",
      "county": "Dumfries and Galloway",
      "postalCode": "DG8 9AB",
      "country": "United Kingdom"
    },
    "organisationId": "org_7eUZfyQq3xxxXXXxJlf",
    "estimatedTimeOfArrival": null,
    "startAfter": null,
    "completeBefore": null,
    "cancellation": null,
  }
}

Payload Expansion

Our REST API supports expansion of nested objects. If you wish to have the webhook payload object expanded to include the full Patient, Task or Window information rather than just the id of the nested object please contact Ally Support.

Retries

The system will try to send the webhook 3 times in the event of a timeout from the configured endpoint, or a status of 4XX or 5XX indicating a failure from the remove system.

Hints and Tips

Start with Test Mode enabled

It is an easy way to created dummy appointments and data without filling up your live views with messy data

View the webhook payload in the webhook detail page

From the Webhooks page click "view" on an existing webhook
Choose "Events" from the side navigation, to a summary of the webhooks sent to date
Choose "View" to view the payload sent to the configured endpoint

Use an external service to see webhook delivery

A good example is beeceptor that makes it easy to create an mock endpoint to view the webhook payload with a couple of clicks

Try out an automation platform to build with ease

Many of the leading automation platforms support being a webook recipient meaning that with no code you can integrate the Ally platform with thousands of leading SaaS platforms.

Zapier (Professional Account is needed) supports a webhook receiver enabling you to do things like send an email to your courier when an Appointment is completed, or update your Salesforce system with the Completion Notes provided by a Practitioner. Please contact our support team for advice in integrating the Ally platform.

Make (free account) supports a webhook receiver and can do many of the things Zapier can do for free up to 1,000 operations per month. The interface is a bit more cluttered, and email is sent via your account (existing SMTP, Google or 365) rather than their hosted service.