Getting Started
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.
Updated 4 months ago