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

Webhooks allow your application to receive real-time notifications when specific events occur in the Solaris platform.

Overview

• Mechanism: Solaris sends a POST request to your exposed HTTPS URL.
• Security: Payloads are signed with HMAC SHA-256 for verification.
• Reliability: Failed deliveries are retried with exponential backoff for up to 5 days.

Managing subscriptions

To receive notifications, you must create a subscription for each event type you want to monitor.

1. Create a subscription

Call the POST /v1/webhooks endpoint with the following payload:

• event_type: The event name (e.g., BOOKING).
• url: Your HTTPS endpoint.

Verification Request: Upon creation, Solaris immediately sends a test POST request to your URL:

• Header: Solaris-Webhook-Event-Type: WEBHOOK-SUBSCRIPTION
• Body: (Empty)

Your server must respond with 200 OK. If successful, the API returns the subscription details, including a secret.

2. Update a subscription

Webhook subscriptions cannot be modified. To change a URL or event type:

1. Delete the existing subscription.
2. Create a new subscription with the updated details.

Handling notifications

Your webhook endpoint must process notifications efficiently and securely.

Response codes

Solaris interprets your HTTP response code to determine the status of the delivery:

Timeouts and async processing

Solaris expects a response within 30 seconds.

Retries and backoff

If delivery fails (non-200 response or timeout), Solaris retries using an exponential backoff strategy:

• Max Attempts: 25
• Backoff Rate: 1.561 (Interval increases by ~56% each time)
• Total Duration: Approximately 5 days before the message is discarded.

Webhook headers

Every notification contains the following HTTP headers. You should use these for routing, identifying resources, and security verification.

Security and verification

You must verify the Solaris-Webhook-Signature header to ensure the request originated from Solaris and has not been tampered with.

The signature is generated using HMAC SHA-256. The key is the secret you received when creating the subscription.

Verification steps

1. Extract the signature from the Solaris-Webhook-Signature header. Note that the value is prefixed with the algorithm (e.g., sha256=...).
2. Read the raw request body (do not parse it as JSON yet).
3. Calculate the HMAC SHA-256 hash of the raw body using your stored secret.
4. Compare your calculated hash with the signature from the header.

Ruby example

signature_header = request.env['HTTP_SOLARIS_WEBHOOK_SIGNATURE']
algorithm, received_signature = signature_header.split('=') # splits "sha256=..."
content = request.body.read

# Calculate expected signature
calculated_signature = OpenSSL::HMAC.hexdigest(
  OpenSSL::Digest.new(algorithm), 
  your_stored_secret, 
  content
)

# Compare signatures (secure comparison is recommended)
if calculated_signature != received_signature
  halt 422, 'Invalid Signature'
end

# Proceed to process the webhook

Mandatory compliance webhooks

You are required to subscribe to these events to remain compliant with banking regulations (e.g., account closures, seizures).

Available webhook events

Click the links below to view the full payload information for each webhook event.