Creating a Webhook

Register an HTTP or Discord webhook from the dashboard or the admin API.

Webhooks are managed through the dashboard or the API, not through the SDK. Creating one requires session authentication and project admin access, because it sends your data to an external system.

From the dashboard

Open your project and go to the Webhooks section, then press Add webhook. The creation flow walks you through the type, the target, and the event or metric to watch:

  1. Type: choose an HTTP webhook or a Discord webhook.
  2. Target: name the webhook, choose where it delivers, and pick the event types it watches, including uptime incident triggers.
  3. Design (Discord only): compose the message and embeds on a live preview.
  4. Review: confirm the configuration, including a resolved preview for a sample event or incident.

After creating an HTTP webhook you are shown its signing secret. This is displayed once, so store it securely. You can edit any webhook later; changes apply to future deliveries only.

Via the API

The same flow is available over the admin API. Create an HTTP webhook by supplying a name, the endpoint URL, and the event types to watch:

http
POST /v1/projects/:projectId/webhooks
Authorization: Bearer vk_...

{
  "type": "http",
  "name": "Billing notifications",
  "url": "https://api.example.com/vanta/events",
  "events": ["payment_failed", "refunded", "incident.started"]
}

A single webhook can watch up to twenty triggers. For a single trigger you can use eventType as a shorthand instead of events. The response includes the webhook id and its signing secret. For Discord webhooks, supply the Discord channel webhook URL instead of your own endpoint.

Signing secret

Every HTTP webhook gets a unique signing secret used to compute the HMAC-SHA256 signature on each delivery. The secret is shown once at creation time. If you lose it, rotate the webhook to generate a new one. Keep it out of client-side code: it is the only way to prove a delivery really came from Vanta.

Endpoint requirements

  • The URL must be publicly reachable over HTTPS.
  • localhost, private IP ranges, and cloud metadata endpoints are rejected at creation time.
  • Your endpoint should respond with a 2xx status to confirm receipt and avoid retries.
  • Handle retries idempotently: the same delivery id can arrive more than once if a previous attempt timed out.