Webhooks - now live!

Late last year, we released an experimental Webhooks notification feature for feedback. That feedback has now been actioned and the Webhooks feature is now fully functional and live in staging. Improvements made since the experimental release are focused on performance, stability, and security.

The basics

The use case for Webhooks is twofold:

1. Removing the need to poll for async query results, which can vastly reduce the number of API calls for many integrators who rely heavily on async and registered queries, and allows integrators to process results as soon as the data is available.
2. Enabling notifications when data changes, via combining Webhooks with Registered Queries. Any data change. There’s no predefined subscriptions. If you can write SQL for it, you can listen for it.

So whether you’re fetching gigs of data for analytics or need to know ASAP when appointments change, Webhooks have you covered

Data security

The other side of the equation is, of course, data security. We do not want to be pushing practice data across the wire any more often than we need to, and we need to be careful about what URLs we’re pushing data to. That lead to three key points of this feature:

1. Webhook payloads do not contain practice data - They are a notification that something happened, not a query result. The payload will only contain the Halo GUID of the practice queried, the ID of the query that triggered the webhook, and the source which is either “async” or “registered”.
2. Webhooks must be enabled for a Halo Cloud subscription by the Halo Connect team - Integrators cannot request a webhook ad-hoc or for specific queries. The webhook URL must be preconfigured and enabled for async and/or registered queries via a manual process, though there are some configuration options — see below.
3. HMAC secret signing - A key request from the feedback period was better assurance for integrators regarding payload origin. Webhooks are now signed using HMAC-SHA256, with a unique secret per integrator, aligned with industry best practices (similar to webhooks in Stripe and GitHub).

Technical Details

To get a bit more technical, we’ve also expanded the metadata available with each webhook and the reliability of delivery. Specifically:

1. Headers: Webhooks contain three headers to help you with identification and trust:
   • X-Halo-Timestamp - ISO 8601 timestamp the webhook was sent on. Note this is different to the date the webhook occurred on which is included in the payload. Used for replay prevention and for HMAC signature verification.
   • X-Halo-Signature-256 - HMAC-SHA256 signature in the format <message_body>.<timestamp_iso8601>.
   • X-Halo-Id - The unique webhook identifier.
2. Retries: Webhooks will automatically retry for up to 2 hours to ensure reliable delivery.

Configuration

To configure webhooks for your subscription, please contact Halo Connect support with the URL you would like webhooks to be sent to. Currently, this can only be a single URL per integrator per environment, however the following optional URL template variables are available:

• {siteId} is replaced with the practice’s Halo GUID
• {queryId} is replaced with the ID of the query that triggered the webhook
• {source} is replaced with the source of the query, either “async” or “registered”

These are the same values included in the webhook payload.

These variables will be replaced with the respective value when the webhook is sent. For example, if an integrator's webhook URL is:

myintegration.com/webhooks/{siteId}

For a practice with Halo GUID 12345, webhooks will be sent to:

myintegration.com/webhooks/12345