Skip to main content
Webhooks allow you to receive notifications when certain events occur in your Sully account.

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

The x-sully-signature header contains:
  • Timestamp (t): The time when the request was signed.
  • Signature (v1): A hash-based message authentication code (HMAC) signature.
Example:
Sully generates signatures using HMAC with SHA-256. You can use the steps below to verify these signatures.

Verifying the Webhook Signature

1. Extract the Timestamp and Signature

Parse the x-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:
  1. The timestamp string.
  2. A . (dot) character.
  3. 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

  1. Constant-time Comparison: Protect against timing attacks by using a secure string comparison.
  2. 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.