NOTE: Signed-secret authentication applies to Sensor, Anomaly, and Data Egress webhook notifications.
Signed Secret Authentication
Use Signed Secret authentication to verify that a webhook request came from SysTrack and that the request body was not changed in transit.
When you configure signed-secret authentication, SysTrack uses the shared secret to compute an HMAC signature for each webhook request. SysTrack sends the computed signature in the x-lakeside-hmac-sha256 request header. Your webhook receiver uses the same secret to compute the signature for the received request body and compares it with the header value.
The secret is not sent in the webhook request. Only the computed signature is sent.
Use the following values when you validate signed-secret webhooks.
Property | Value |
|---|---|
Authentication method | Signed Secret |
Signature header |
|
Algorithm | HMAC-SHA256 |
Signature encoding | Base64 |
Signed content | Raw request body, exactly as received |
Secret | Customer-provided value or system-generated value from Generate New |
Configure Signed Secret Authentication
In the webhook configuration, select Signed Secret as the Authentication Method.
Enter your own secret, or click Generate New.
Store the secret in a secure location.
IMPORTANT: The secret is not displayed again after the webhook is saved.
Configure your webhook receiver to validate the
x-lakeside-hmac-sha256header by using the same secret.
Validate Signed Secret Webhooks
To validate a signed-secret webhook, your receiver must compute an HMAC-SHA256 signature over the raw request body and compare it with the value in the x-lakeside-hmac-sha256 header.
Use this validation order:
Capture the raw request body exactly as received.
Compute an HMAC-SHA256 hash over the raw request body by using the shared secret.
Base64-encode the computed hash.
Compare the computed value with the
x-lakeside-hmac-sha256header value.Parse and process the JSON payload only after validation succeeds.
IMPORTANT: Validate the signature against the raw request body bytes exactly as received. Do not parse the JSON and then reserialize it before computing the HMAC. Changes to whitespace, indentation, key order, or line endings produce a different signature and cause validation to fail.
Use a constant-time comparison when you compare signatures, if your programming language or framework supports it. Constant-time comparison helps reduce the risk of timing-based attacks.
Base64 values are case-sensitive. If you use a string comparison, use a case-sensitive comparison.
Validation Code Examples
Python
import base64
import hashlib
import hmac
def is_valid(raw_body: bytes, received_signature: str, secret: str) -> bool:
computed_signature = base64.b64encode(
hmac.new(
secret.encode("utf-8"),
raw_body,
hashlib.sha256
).digest()
).decode("utf-8")
return hmac.compare_digest(computed_signature, received_signature)PowerShell
$secret = "<your-webhook-secret>"
$received = $headers["x-lakeside-hmac-sha256"]
$bodyBytes = [System.Text.Encoding]::UTF8.GetBytes($rawBody) # raw body as received
$hmac = [System.Security.Cryptography.HMACSHA256]::new(
[System.Text.Encoding]::UTF8.GetBytes($secret)
)
try {
$computed = [Convert]::ToBase64String($hmac.ComputeHash($bodyBytes))
}
finally {
$hmac.Dispose()
}
$isValid = $computed -ceq $received # -ceq is case-sensitive (Base64 is case-sensitive)FAQ
How do I validate a signed-secret webhook?
When you use signed-secret authentication, SysTrack sends a Base64-encoded HMAC-SHA256 signature in the x-lakeside-hmac-sha256 header. Your webhook receiver must compute an HMAC-SHA256 signature over the raw request body by using the same secret and compare the computed value with the header value.
Validate the raw request body exactly as received. Do not parse and reserialize the JSON before computing the signature.