Skip to main content
This guide sets up a webhook integration so your server receives real-time POST notifications when events happen in Vanta instead of polling the API. You’ll register an endpoint, implement a handler that verifies signatures, and confirm an event end to end.

​
Before you begin

This guide is for developers building a server that receives Vanta webhooks. You’ll need:
  • A publicly accessible HTTPS endpoint on your server to receive webhook POST requests.
  • Access to Settings → Webhooks in the Vanta dashboard, to register the endpoint and copy its signing secret.
  • The official Svix library for your language — recommended for signature verification.
Webhooks are powered by Svix, an enterprise webhook delivery platform, so you get automatic retries, delivery guarantees, and signature verification out of the box. For the full event catalog, payloads, and schemas, see the Webhook event reference.
1

Register your endpoint

In the Vanta dashboard, register the URL that will receive events. An endpoint is a URL on your server that receives webhook POST requests from Vanta.
  1. Navigate to Settings → Webhooks.
  2. Click Add Endpoint.
  3. Enter your endpoint URL (must be HTTPS).
  4. Browse the available event types and select the ones relevant to your integration — see the Webhook event reference for the full catalog of events, payloads, and schemas. Leave the selection blank to receive all events.
  5. Click Create to register the endpoint.
Then open the endpoint and copy its Signing Secret (it starts with whsec_) from the Signing Secret section — you’ll use it to verify signatures in the next steps.
2

Implement your handler

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().
Keep the following in mind as you build:
Your endpoint must be publicly accessible over HTTPS.
Return a 2xx status code within 15 seconds to acknowledge receipt. If you don’t, the delivery is marked as failed and retried.
Webhook requests won’t include CSRF tokens, so CSRF protection must be disabled for the webhook endpoint.
Return a 2xx immediately, then handle the event in a background job or queue. This prevents timeouts on long-running operations.
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.
3

Verify webhook signatures

Webhook signatures let you confirm that messages are actually sent by Vanta and not a malicious third party. Verification isn’t strictly required, but always verify signatures in production.Each webhook message includes svix-id, svix-timestamp, and svix-signature headers used for verification — see Delivery format in the event reference for what each header contains.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.
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");
  }
});
If you prefer not to use a library, you can verify signatures manually:
  1. Extract the svix-id, svix-timestamp, and svix-signature headers.
  2. Concatenate {svix-id}.{svix-timestamp}.{body} (the raw request body as a string).
  3. Base64-decode the signing secret (remove the whsec_ prefix first).
  4. Compute an HMAC-SHA256 of the signed content using the decoded secret.
  5. Base64-encode the result and compare it against the signature(s) in the svix-signature header (split by space, each prefixed with v1,).
Also verify that the svix-timestamp is recent (within 5 minutes) to prevent replay attacks.
4

Test your endpoint

Before going to production, confirm your endpoint can receive and process webhooks correctly.
  1. Go to Settings → Webhooks in the Vanta dashboard.
  2. Select the endpoint you want to test.
  3. Navigate to the Testing tab.
  4. Choose an event type and click Send Example.
This sends a test message with an example payload to your endpoint, letting you confirm your server verifies and handles it correctly.
  • 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.
  • 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.
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.
If your endpoint was down for an extended period, 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.

​
Congratulations

You’ve built a webhook integration. Your endpoint now receives verified, real-time events from Vanta, acknowledges them within the retry window, and processes them idempotently — no polling required. As you add event types to your subscription, consult the Webhook event reference for each one’s payload and schema.

​
Next steps

Webhook event reference

Browse every event type, with payloads, schemas, and examples.

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.