Webhooks Overview

Trace webhooks send real-time HTTP POST requests to your configured endpoint URLs whenever important security events occur — such as new vulnerabilities being detected, status changes, and severity updates. This allows you to build automated workflows for triage, alerting, ticketing, and compliance reporting.

How webhooks work

When an event occurs in your Trace organization, Trace sends an HTTP POST request to each registered webhook endpoint that subscribes to that event type. The request body contains a JSON payload describing the event.

POST https://your-server.com/webhooks/trace
Content-Type: application/json
X-Trace-Event: vulnerability.detected
X-Trace-Delivery: a]1b2c3d4-e5f6-7890-abcd-ef1234567890
X-Trace-Signature: sha256=d57c68ca6f92289e6987922ff26938930f6e66a2d161ef06abdf1859230aa23c

Delivery headers

Every webhook delivery includes the following HTTP headers:

Verifying webhook signatures

Every webhook delivery is signed using your webhook secret so you can verify that the payload was sent by Trace and has not been tampered with.

To verify a delivery:

1. Extract the signature from the X-Trace-Signature header.
2. Compute the HMAC-SHA256 digest of the raw request body using your webhook secret.
3. Compare the computed signature with the header value using a constant-time comparison.

import crypto from "crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload, "utf8")
    .digest("hex");

  const expectedBuffer = Buffer.from(`sha256=${expected}`, "utf8");
  const signatureBuffer = Buffer.from(signature, "utf8");

  return (
    expectedBuffer.length === signatureBuffer.length &&
    crypto.timingSafeEqual(expectedBuffer, signatureBuffer)
  );
}

Retry policy

If your endpoint returns a non-2xx status code or does not respond within 30 seconds, Trace will retry the delivery using exponential backoff:

After 5 failed retries, the delivery is marked as failed. You can view and manually re-trigger failed deliveries from the Trace dashboard.

Event payload structure

All webhook payloads share a common envelope structure:

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "vulnerability.detected",
  "createdAt": "2026-03-04T18:00:00.000Z",
  "organizationId": "org_abc123",
  "data": {
    // Event-specific payload — see individual event documentation
  }
}

Subscribing to events

You can configure webhooks from the Trace dashboard under Settings → Webhooks. When creating a webhook, you specify:

• Endpoint URL — The HTTPS URL that will receive webhook deliveries.
• Secret — A shared secret used to sign deliveries for verification.
• Events — The specific event types you want to subscribe to, or subscribe to all events.

Best practices

• Always verify signatures — Reject any delivery that fails signature verification.
• Respond quickly — Return a 200 status code as fast as possible. Process the payload asynchronously.
• Use idempotency — Use the id field to deduplicate events in case of retries.
• Subscribe selectively — Only subscribe to the events you need to reduce noise.
• Use HTTPS — Webhook endpoints must use HTTPS to ensure payloads are encrypted in transit.