Webhooks

Introduction

Webhooks are a form of server-to-server communication which send notifications as soon as specific events occur. By subscribing to webhooks, you can reduce the number of API calls that your solution makes and build your solution to react to important events in real time.

This guide explains how to subscribe to webhooks and contains an explanation and sample payload for each webhook event.

How to subscribe to a webhook

note

Please note that webhooks are intended for informational purposes only. Your solution's business logic should not directly use the contents of the webhook payload (with the exception of seizure-related webhooks). Please use the Solaris API's GET endpoints to retrieve information about resources for your business logic.

First, your solution must expose a URL (HTTPS) where Solaris can send webhook notifications.

Then, for each event type you wish to subscribe to, you must call the POST Create a webhook subscription method. Supply the following in the request:

  • event_type: The type of webhook event to subscribe to.
  • url: The URL to which Solaris will send the webhook notification.

When you register a new webhook subscription, the Solaris API will check the availability of the provided URL by sending a single POST notification. The notification does not include a body, but it includes the SOLARIS-WEBHOOK-EVENT-TYPE header with a value of WEBHOOK-SUBSCRIPTION.

If your URL returns a 2XX HTTP response code, then the Solaris API will create the webhook subscription and return you a 201 Created response. In the response body, you will find the secret property. You must use the value of this property to verify the authenticity of Solaris webhook notifications. The API only exposes this secret once, so if you misplace it, then you must register a new webhook subscription.

How to update a webhook subscription

Once a webhook subscription has been created, it cannot be modified. You must delete the webhook subscription and register a new one with the desired updated properties.

Webhook notification delivery

Implement the following HTTP response codes for the URL where your solution will receive webhook notifications:

Response Code Reaction
2xx - Success Solaris' webhook service assumes that the notification was successfully delivered.
410 - Gone Solaris' webhook service marks the notification delivery as rejected and cancels the subscription on this particular URL.
422 - Unprocessable Entity The delivery is marked as rejected, and Solaris' webhook service will not re-attempt to deliver the notification.

Any response code not listed above will place the webhook notification into a retry loop. The Solaris webhook service keeps track of the number of retries using a header; with each failed delivery, it will increase the count. After 20 unsuccessful retries over a period of seven days, the message will automatically expire.

Notification content

A webhook notification consists of two parts:

  • Metadata: Information stored in the HTTP header. This could be information related to the webhook subscription itself (consistent across all webhook types) or it could include IDs of entities (e.g., person IDs) related to the webhook event that caused the notification.
  • Payload: Information stored in the HTTP body. This usually contains all of the properties of the resource related to the webhook event that caused the notification.

Full list of webhook headers

Each webhook notification will contain the following headers:

  • Content-Type: The media type of the webhook notification content.
  • Solaris-Webhook-Id: ID of the webhook itself.
  • Solaris-Webhook-Subscription-Id: ID of the subscription you created for the webhook event.
  • Solaris-Webhook-Event-Type: The event type of the webhook notification. See the section below for a full list.
  • Solaris-Entity-Id: ID of the Solaris entity related to the webhook notification. For example, in a PERSON_DELETED webhook notification, this header would contain the ID of a person whose data you must delete.
  • Solaris-Webhook-Attempt: Indicates the number of times Solaris has attempted to deliver the webhook notification.
  • Solaris-Webhook-Signature: SHA256 signature that you must use to verify the authenticity of the webhook. See the next section for more information.
  • Solaris-Webhook-Callout-Timestamp: UTC timestamp from when the webhook notification was sent.
  • User-Agent: Indicates the user agent that generated the webhook notification on Solaris' side.

Content verification

Solaris provides a signature hash in each webhook notification as the value of the Solaris-Webhook-Signature header. This allows you to verify that the notification really came from Solaris and protect against misuse of your webhook URL.

The webhook service generates the signature using the HMAC algorithm. It uses the secret from the webhook subscription as the HMAC key to encrypt the payload, and it encodes the digest used for the signature generation in the header. The Solaris-Webhook-Subscription-Id header references the relevant secret for calculating the signature.

We recommend that you use the raw message payload to generate a signature hash to verify the one received in the header. This ensures your implementation will not break in case additional fields are introduced. Moreover, calculating on the raw message will ensure that parsing errors do not compromise your ability to verify the authenticity of your webhook traffic.

Here is a Ruby example of how to validate a message by its signature:

Copy
Copied
digest_algorithm, signature = request.env['HTTP_SOLARIS_WEBHOOK_SIGNATURE'].split('=')
content = request.body.read

if OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new(digest_algorithm), secret, content) != signature
  halt(422, 'Signature not correct')
end

# process notification

Mandatory webhook events

You are required to subscribe to the following webhook events for compliance purposes:

Beyond compliance requirements, different products require different webhook subscriptions in order to function well. Check the respective product feature guide to learn about which webhooks a particular product requires.

Full list of webhook events

Click the links below to see the full payload information for each webhook event: