Webhooks

Subscribe to Vanta events and receive real-time HTTP notifications instead of polling the API.

Webhooks are powered by Svix, an enterprise webhook delivery platform. This means you get automatic retries, delivery guarantees, and signature verification out of the box.

Setting up webhooks

To start receiving webhooks, you need to register at least one endpoint. An endpoint is a URL on your server that will receive webhook POST requests from Vanta.

1. Navigate to Webhooks settings

   Navigate to Settings > Webhooks in the Vanta dashboard.

2. Add Endpoint

   Click Add Endpoint.

3. Enter your endpoint URL

   Enter the URL of your endpoint (must be HTTPS).

4. Select event types

   Browse the available event types, each one includes a description and payload schema. Select the ones relevant to your integration. Leave the selection blank to receive all events.

5. Create

   Click Create to register the webhook event.

Implementing your endpoint

Once your webhook is registered, implement a server-side handler that can receive the webhook request you just configured.

Signature verification requires the raw request body as a string, not a parsed object. Make sure your framework preserves the raw body on the webhook route. For example, in Express use express.raw({ type: 'application/json' }) instead of express.json().

When you’re building, you’ll want to keep the following in mind.

Expose your endpoint over HTTPS

Your endpoint must be publicly accessible over HTTPS.

Respond with a 2xx within 15 seconds

Return a 2xx status code within 15 seconds to acknowledge receipt. If you don’t, the delivery will be marked as failed and retried.

Disable CSRF protection on the webhook route

Webhook requests won’t include CSRF tokens, so CSRF protection must be disabled for the webhook endpoint.

Process payloads asynchronously

Return a 2xx immediately, then handle the event in a background job or queue. This prevents timeouts on long-running operations.

Implement idempotent handling

Webhook delivery is “at least once,” so your endpoint may receive the same event more than once. Use the svix-id header to deduplicate events.

Testing your endpoint

Before going to production, you should verify that your endpoint can receive and process webhooks correctly.

1. Open the Webhooks dashboard

   Go to Settings > Webhooks in the Vanta dashboard.

2. Select your endpoint

   Select the endpoint you want to test.

3. Open the Testing tab

   Navigate to the Testing tab.

4. Send an example event

   Choose an event type and click Send Example.

This will send a test message with an example payload to your endpoint, letting you confirm that your server handles it correctly.

Verifying webhook signatures

Webhook signatures let you verify that webhook messages are actually sent by Vanta and not by a malicious third party. Signature verification isn’t strictly required, but always verify signatures in production.

Each webhook message includes three headers used for verification:

Header	Description
svix-id	The unique message identifier.
svix-timestamp	The timestamp of the message attempt (seconds since epoch).
svix-signature	The Base64-encoded signature(s), space-delimited.

The simplest way to verify signatures is to use the official Svix libraries. Install the library for your language and use the Webhook.verify method.

You can find your endpoint’s signing secret in the Vanta webhook dashboard by clicking the endpoint and looking in the Signing Secret section.

Node.js

import { Webhook } from "svix";

const secret = "whsec_..."; // Your signing secret

const wh = new Webhook(secret);

app.post("/webhook", (req, res) => {
  try {
    const payload = wh.verify(req.body, req.headers);
    // payload is the verified JSON body
    console.log("Verified webhook:", payload);
    res.status(200).send("OK");
  } catch (err) {
    console.error("Verification failed:", err.message);
    res.status(400).send("Invalid signature");
  }
});

Manual verification

If you prefer not to use a library, you can verify signatures manually:

1. Extract the headers

   Extract the svix-id, svix-timestamp, and svix-signature headers.

2. Construct the signed content

   Concatenate: {svix-id}.{svix-timestamp}.{body} (the raw request body as a string).

3. Decode the signing secret

   Base64-decode the signing secret (remove the whsec_ prefix first).

4. Compute the HMAC

   Compute an HMAC-SHA256 of the signed content using the decoded secret.

5. Compare signatures

   Base64-encode the result and compare it against the signature(s) in the svix-signature header (split by space, each prefixed with v1,).

You should also verify that the svix-timestamp is recent (within 5 minutes) to prevent replay attacks.

Retry schedule

A response is considered failed if the server doesn’t respond with a 2xx status code within 15 seconds, including network timeouts.

If your endpoint fails to respond with a 2xx status code, Vanta will automatically retry the delivery using an exponential backoff schedule:

Attempt	Delay after previous attempt
1	Immediately
2	5 seconds
3	5 minutes
4	30 minutes
5	2 hours
6	8 hours
7	1 day
8	2 days

After all retry attempts are exhausted (approximately 5 days total), the message is marked as failed.

You can also manually retry failed messages from the webhook dashboard by navigating to the endpoint and clicking Retry on a specific message.

Troubleshooting

Webhook requests are failing with 4xx errors

• Verify that your endpoint URL is correct and publicly accessible over HTTPS.
• Ensure that CSRF protection is disabled for the webhook endpoint.
• Check that your server is returning a 2xx status code.

Signature verification is failing

• Make sure you are using the raw request body (not a parsed JSON object) when verifying the signature.
• Confirm that the signing secret matches the one displayed in the webhook dashboard.
• Check that you haven’t accidentally modified or re-serialized the request body before verification.

Webhook requests are timing out

Your endpoint must respond within 15 seconds. If your processing takes longer, acknowledge the webhook immediately with a 200 response and handle the event asynchronously in a background job or queue.

Recovering missed events

If your endpoint was down for an extended period, you can recover missed events through the webhook dashboard:

1. Go to Settings > Webhooks.
2. Select the affected endpoint.
3. Browse the message history to find failed deliveries.
4. Click Retry on individual messages, or use Bulk Retry to replay all failed messages within a time range.

Next steps

Manage Vanta

Use webhooks alongside the Manage Vanta API to react to events in real time.

Build an Integration

Become a Vanta partner and push resources into customers’ Vanta accounts.