Ways to run

Webhooks

Get a signed verification.completed event when a verification finalizes, and check its signature.

Outcome

Your systems get each decision as it lands, and can check it came from Vraelis.

Does not do

A delivery carries the decision, counts, ids and a link to the evidence, never a session id, token, credential or signed artifact URL.

Connect an endpoint and Vraelis POSTs a signed verification.completed event the moment a verification finalizes. It carries only owner-safe facts: the decision, flow counts, ids, and a link to the evidence. Never a session id, token, credential, or signed artifact URL.

Add an endpoint

Add it under Developers in the console. The endpoint gets its own signing secret, which starts with whsec_. The console shows it when you add the endpoint, Reveal shows it again, and Rotate replaces it. Send test posts a sample event marked "test_event": true. Open Developers in the console

• The address must be https on port 443, on a public host. Localhost and private addresses are refused.
• A delivery that times out, or gets a 5xx or 429 answer, is tried again, up to five attempts in all. Deliveries lists the recent ones, and Retry sends a failed one again.
• An account can have up to 10 endpoints. Every finished verification goes to each one that is enabled.

The event

One event, verification.completed, delivered with the headers x-vraelis-event, x-vraelis-timestamp, and x-vraelis-signature.

Each delivery also carries an x-vraelis-delivery header, with the same id as delivery_id in the body. A retry keeps that id, so a receiver can drop a repeat.

{
  "event": "verification.completed",
  "run_id": "9c1e0f2a41",
  "application_id": "app_5b7d",
  "decision": "failed",
  "flows_total": 4,
  "flows_passed": 3,
  "deployment_url": "https://staging.example.com",
  "completed_at": "2026-09-28T18:04:11.220Z",
  "report_url": "https://app.vraelis.com/systems/app_5b7d/passes/9c1e0f2a41",
  "delivery_id": "5f0c2e8a-1b7d-4c39-9e2a-0f2a41c1e9d6"
}

Verify a delivery

The signature is an HMAC over the raw body prefixed with the timestamp, so recompute over the exact bytes you received before trusting the payload.

Key the HMAC with the endpoint's signing secret, and keep the secret on your server, for example in an environment variable.

// Verify the delivery: HMAC-SHA256 over `${timestamp}.${rawBody}`, keyed with the endpoint's
// signing secret (whsec_...), which the console shows under Developers.
import { createHmac, timingSafeEqual } from "node:crypto";

const timestamp = req.headers["x-vraelis-timestamp"];
const signature = req.headers["x-vraelis-signature"];   // "sha256=<hex>"
const expected = "sha256=" + createHmac("sha256", process.env.VRAELIS_WEBHOOK_SECRET)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");

const ok = Boolean(signature) && signature.length === expected.length
  && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

Slack, and webhooks on one system

A system can also send the event itself: add a Webhook or a Slack connection in its settings, under Connections. A Slack incoming webhook gets the event as a formatted message in your channel instead of raw JSON, with the decision, flows passed, and a link to the evidence.

These deliveries carry no delivery_id and are not retried, and a Webhook connection has no signing secret of its own. When a receiver has to check where a delivery came from, add its endpoint under Developers.

Related

• The API →
• Gate a release in CI →
• Completion →