Webhook Security
Secure your Sully webhook integrations by verifying that incoming requests are authentic. Sully sends an x-sully-signature header with every webhook request, allowing you to validate its integrity.Structure of the Signature Header
Thex-sully-signature
header contains:
- Timestamp (
t
): The time when the request was signed. - Signature (
v1
): A hash-based message authentication code (HMAC) signature.
Verifying the Webhook Signature
1. Extract the Timestamp and Signature
Parse thex-sully-signature
header to retrieve the timestamp (t
) and the signature (v1
).
2. Prepare the signed_payload
String
The signed_payload
is a concatenation of:
- The timestamp string.
- A
.
(dot) character. - The raw body of the webhook request.
3. Compute the Expected Signature
Generate the HMAC-SHA256 signature using:- Key: Your webhook’s signing secret.
- Message: The signed_payload.
4. Validate the Signature and Timestamp
- Constant-time Comparison: Protect against timing attacks by using a secure string comparison.
- Timestamp Validation: Ensure the timestamp is recent (e.g., within 5 minutes) to mitigate replay attacks.
Full Example
Notes
- Ensure the body passed to isValidSignature is the raw, unparsed payload.
- Adjust the timestamp tolerance (toleranceInSeconds) based on your security requirements.
- Log validation errors for debugging but avoid exposing sensitive details.