Sunlight uses webhooks to send updates about your user’s state or data.
- 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
POSTpayloads in raw JSON to your webhook URL.
Sunlight uses signature verification security mechanism for the webhooks.
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
This step is optional but recommended.
Keep in mind
The secret should never be exposed publicly.
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.
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.
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