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
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
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
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:
||Solaris' webhook service assumes that the
||Solaris' webhook service marks the
||The delivery is marked as rejected, and Solaris' webhook service will not re-attempt to deliver the
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.
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.
Solaris provides a signature hash in each webhook notification as the value
Solaris-Webhook-Signature header. This allows you to verify that the
notification really came from Solaris and protect against misuse of your webhook
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
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:
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: