Webhooks

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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.

Before you begin

Make sure you have the following:

• A service URL (HTTPS) exposed on your server to receive POST requests.
• Your API credentials to create the subscription.

How to subscribe to a webhook

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:

Timeout and Retries

Solaris expects a response from your server within 30 seconds.

If the delivery fails or times out, the notification enters a retry loop using an exponential backoff strategy:

• Timeout: 30 seconds
• Maximum attempts: 25
• Initial interval: 5 seconds
• Backoff rate: 1.561

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 header value is prefixed with the hashing algorithm (for example, sha256=).

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:

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

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

# 2. Signature valid. Enqueue background job to process data asynchronously.
# (Do not process heavy logic here to avoid the 30s timeout)
BackgroundJob.enqueue(content)

# 3. Acknowledge receipt immediately
status 200

Mandatory webhook events

You are required to subscribe to specific 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.