Copy the prompt to run this live via the MCP server or have AI generate a runnable script.
{children}
;
export const WEBHOOK_BUILD = "You are writing a production-quality Node.js 18+ webhook receiver using Express that ingests Vanta webhook events, verifies their signatures, and processes them idempotently. Vanta delivers webhooks through Svix, so use the official svix library to verify signatures.\n\nSteps:\n\n1. Read VANTA_WEBHOOK_SIGNING_SECRET (the endpoint signing secret, starts with whsec_) and PORT (default 3000) from env. Fail fast on stderr if the signing secret is missing — never hard-code it.\n2. Use only express and svix (npm i express svix). On the webhook route, use express.raw({ type: 'application/json' }) so the RAW request body is preserved as a Buffer. Signature verification fails if the body has been parsed or re-serialized, so do NOT use express.json() on this route.\n3. Expose POST /webhooks. Build a Svix Webhook from the signing secret and call wh.verify(rawBody, headers), passing the svix-id, svix-timestamp, and svix-signature headers. If verification throws, respond 400 and stop.\n4. Deduplicate on the svix-id header (delivery is at-least-once). Keep a bounded in-memory Set (or a persistent store in production) of processed svix-id values; if the id was already seen, respond 200 and stop without reprocessing.\n5. Acknowledge fast: respond 200 within 15 seconds, BEFORE doing any slow work. Hand the verified event to an async queue or handler — do not block the HTTP response on processing.\n6. In the async handler, branch on the event type (for example v1.questionnaire.status-changed, v1.vendor.decision.created, v1.trust-center.access-request.approved). The verified JSON body matches the payload documented for that event type in the Vanta webhook event reference. Treat all IDs as opaque strings; to fetch the full object, call the matching Manage Vanta API endpoint.\n7. Log one structured line per event: svix-id | event type | outcome (processed / duplicate / error). Never log the signing secret.\n8. Add a GET /healthz route that returns 200 for liveness checks.\n\nMissing-field handling: if an expected payload field is absent, log a warning and continue — never throw inside the request handler in a way that prevents the 200 acknowledgement.\n\nError handling:\n- Invalid signature: respond 400, log the svix-id, do not process.\n- Processing failure in the async handler: log it and rely on Vanta's automatic retries — do NOT return a non-2xx after you have already acknowledged.\n- Malformed or oversized body: respond 400.\n\nDo not:\n- Add dependencies beyond express and svix.\n- Use express.json() on the webhook route, or verify against a parsed or re-serialized body.\n- Block the 200 response on downstream processing.\n- Hard-code or log the signing secret.\n- Disable signature verification in production.\n\nDone when: a Svix \"Send Example\" test event is received on POST /webhooks, passes signature verification, is acknowledged with 200 within 15 seconds, processed exactly once (a redelivery with the same svix-id is skipped), and logged.\n\nRequires: an HTTPS-reachable endpoint and the endpoint signing secret from Settings → Webhooks.";
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](https://www.svix.com/) library for your language — recommended for signature verification.
Webhooks are powered by [Svix](https://www.svix.com/), 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](/reference/webhooks/overview).
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](/reference/webhooks/overview) 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.
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](/reference/webhooks/overview#retry-schedule).
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.
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](/reference/webhooks/overview#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.
```javascript Node.js theme={"system"}
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");
}
});
```
```python Python theme={"system"}
from svix.webhooks import Webhook
secret = "whsec_..." # Your signing secret
wh = Webhook(secret)
def handle_webhook(request):
try:
payload = wh.verify(request.body, request.headers)
# payload is the verified dict
print("Verified webhook:", payload)
return HttpResponse(status=200)
except Exception as e:
print("Verification failed:", e)
return HttpResponse(status=400)
```
```go Go theme={"system"}
import svix "github.com/svix/svix-webhooks/go"
secret := "whsec_..." // Your signing secret
wh, _ := svix.NewWebhook(secret)
func handleWebhook(w http.ResponseWriter, r *http.Request) {
payload, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "Bad request", http.StatusBadRequest)
return
}
err = wh.Verify(payload, r.Header)
if err != nil {
http.Error(w, "Invalid signature", http.StatusBadRequest)
return
}
// payload is verified
w.WriteHeader(http.StatusOK)
}
```
```ruby Ruby theme={"system"}
require "svix"
secret = "whsec_..." # Your signing secret
wh = Svix::Webhook.new(secret)
post "/webhook" do
begin
payload = wh.verify(request.body.read, request.env)
# payload is the verified hash
puts "Verified webhook: #{payload}"
status 200
rescue Svix::WebhookVerificationError => e
puts "Verification failed: #{e.message}"
status 400
end
end
```
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.
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](/reference/webhooks/overview) for each one's payload and schema.
## Next steps
Browse every event type, with payloads, schemas, and examples.
Use webhooks alongside the Manage Vanta API to react to events in real time.
Become a Vanta partner and push resources into customers' Vanta accounts.