Skip to main content
When Veritus Agent sends webhooks to your application, we include cryptographic signatures to ensure the authenticity and integrity of the webhook payload. This guide explains how webhook signatures work and how to verify them.

​
Overview

Veritus Agent uses HMAC SHA-256 signatures to sign all webhook payloads. When you configure a webhook with a secret, we’ll include signature headers with every webhook request that allow you to verify:
  1. The webhook came from Veritus Agent (authenticity)
  2. The payload hasn’t been tampered with (integrity)
  3. The webhook isn’t being replayed (freshness via timestamp)

​
Webhook Secrets

​
What is a Webhook Secret?

A webhook secret is a shared cryptographic key used to generate signatures for your webhooks. You’ll receive a secretId from Veritus Agent that references your webhook secret stored securely in our system.

​
How to Get a Webhook Secret

Webhook secrets can be generated in your organization’s portal. You may also contact your Veritus Agent representative to create a webhook secret for your organization. They will provide you with:
  • A secretId - Used to reference the secret when making API calls
  • The actual secret value - Used to verify webhook signatures (store this securely!)
Store your webhook secret securely! Anyone with access to this secret can forge valid webhook signatures. Never commit secrets to version control or expose them in client-side code.

​
Using Webhook Secrets

​
Signature Headers

When a webhook secret is configured, Veritus Agent includes two headers with every webhook request:
  • X-Webhook-Signature - The HMAC SHA-256 signature
  • X-Webhook-Timestamp - Unix timestamp (in seconds) when the webhook was sent

​
Verifying Webhook Signatures

​
Step 1: Extract the Headers

Extract the signature and timestamp from the webhook request headers.

​
Step 2: Prepare the Signed Content

Concatenate the timestamp, a period, and the raw JSON payload: 
{timestamp}.{json_payload}
Use the raw JSON body as a string, not a parsed object. The signature is computed on the exact bytes received.

​
Step 3: Compute the Expected Signature

Generate an HMAC SHA-256 signature using your webhook secret and the signed content from Step 2. The signature format is: 
sha256={hex_encoded_hmac}

​
Step 4: Compare Signatures

Use a constant-time comparison to prevent timing attacks when comparing the received signature with your computed signature.

​
Step 5: Verify Timestamp

Check that the timestamp is recent to prevent replay attacks. We recommend rejecting webhooks older than 5 minutes.