Sunlight uses webhooks to send updates about your user’s state or data.

Format

• Webhooks are configured separately for production & mock environments.
• The URL must be in the standard format of <https://domain.com/path> and must have a valid SSL certificate.
• Sunlight sends POST payloads in raw JSON to your webhook URL.

Security

Sunlight uses signature verification security mechanism for the webhooks.

Using the secret key from API credentials, you can validate that the webhook is from Sunlight.

A special header named x-sunlight-signature is added to the webhook requests for this verification. This signature is calculated using HMAC with the SHA256 algorithm, with your secret set as the key and the webhook request body as the message. the header is in Hex encoded format.

You can validate the webhook signature using an HMAC as shown below:

key = secret_key
message = webhook_body // raw webhook request body
received_signature = webhook_signature

expected_signature = hmac('sha256', message, key)

if expected_signature != received_signature
    throw Error // signature mismatch - content should be ignored
end

📘

Info

This step is optional but recommended.

🚧

Keep in mind

The secret should never be exposed publicly.

Timeout

A webhook call times out after 5 seconds. If we do not receive a successful response within that time frame, we mark the webhook delivery as failed and go into retry mechanisms.

📘

Info

Since the webhook has a small window for timeout, you should not block it or make it dependent on another process or API call. Instead, you should return a succesful response as acknowledgement and then keep running your logic in a separate thread.

Idempotency

In cases of failure (response with non 200 HTTP status) or timeout, it is assumed that the webhook has not been processed and is sent again as per the retry policy. Ensure your server is configured to handle or receive the same event details multiple times.