Webhooks

Send signed events about requests to your own systems: the events, the payload, checking the signature, retries and limits.

A webhook sends a signed event to an address of yours whenever something happens to a request: it waits for a person, is approved, denied, expires or is withdrawn. A serverless agent, n8n, a workflow engine or an internal tool then hears about it at once, without asking every few seconds. Webhooks are part of Pro and up.

A webhook is a notification, never a permission. It has no allowed field on purpose. Before the agent acts, it reads GET /v1/requests/{id} with its own key and acts only when allowed is true. That read also applies an emergency stop that came after the decision, which no event you received earlier can know about.

Add a webhook

  1. Open Settings and find Webhooks. Only owners can add or change them; everyone in the workspace can see them.
  2. Paste the address that should receive events, give it a label, and choose its events.
  3. Choose Add webhook, and copy the signing secret it shows. It starts with whsec_ and is shown only this once.
  4. Choose Send test. A webhook.test event arrives within seconds, and Show recent deliveries says what your side answered.

The address is kept secret, since it can hold your own tokens: after it is added, only its host is shown, and it is never logged.

Events

request.waiting
A request waits for a person.
request.approved
A person approved it, or an allow rule did. Two-person approval sends this once, when the last approval lands.
request.denied
A person denied it, or a deny rule did.
request.expired
Nobody decided before its deadline. Sent about a minute after the deadline.
request.withdrawn
The agent took it back before anyone decided.
request.outcome
The agent said whether the approved action succeeded.
webhook.test
Sent when an owner chooses Send test, whatever events the webhook asked for.

What is sent

Each event is a POST with a JSON body and three headers, as the Standard Webhooks spec describes:

POST /variantgate HTTP/1.1
content-type: application/json
user-agent: VariantGate-Webhooks/1
webhook-id: 0196f1a2-7c4e-7d10-9a3b-2c5e8f1d4a60
webhook-timestamp: 1794821472
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
webhook-id
The event's id, the same on every attempt. Use it to drop an event you already handled.
webhook-timestamp
When this attempt was signed, in Unix seconds.
webhook-signature
v1, a comma, and the base64 of the signature.

The body of an approval:

{
  "id": "0196f1a2-7c4e-7d10-9a3b-2c5e8f1d4a60",
  "type": "request.approved",
  "timestamp": "2026-11-16T09:31:12.408113Z",
  "workspace_id": "0196f19c-1b2a-7e45-8d3c-6a7b9c0d1e2f",
  "data": {
    "request_id": "0196f1a0-55d2-7a11-b3e4-9f8e7d6c5b4a",
    "agent": "billing-bot",
    "key_name": "billing-bot",
    "action": "payment.refund",
    "summary": "Refund €49.00 to ana@example.com for order 1182",
    "amount": "49.00",
    "currency": "EUR",
    "status": "approved",
    "decided_by": "maya@northwind.example",
    "by_rule": false,
    "rule_id": null,
    "decision_note": "Customer called; fine.",
    "changed": false,
    "approved_summary": "Refund €49.00 to ana@example.com for order 1182",
    "approved_amount": "49.00",
    "outcome": null,
    "outcome_note": null,
    "created_at": "2026-11-16T09:30:02.112233Z",
    "expires_at": "2026-11-16T09:45:02.112233Z",
    "decided_at": "2026-11-16T09:31:12.408113Z",
    "url": "https://variantgate.com/inbox?workspace=0196f19c-1b2a-7e45-8d3c-6a7b9c0d1e2f#inbox?request=0196f1a0-55d2-7a11-b3e4-9f8e7d6c5b4a"
  }
}
type
One of the events above.
id, timestamp
The event's id, and when it happened.
workspace_id
The workspace the request is in.
data.request_id
The request. Read it with GET /v1/requests/{id} before acting.
data.agent, key_name
The name the agent gave itself, and the name of its key.
data.action, summary
What the agent asked to do.
data.amount, currency
The money it would move, if any.
data.status
pending, approved, denied, expired or withdrawn.
data.decided_by, by_rule
Who decided: a person's email, or the owner who wrote the rule, with by_rule true.
data.decision_note
What the person or the rule said.
data.changed, approved_summary, approved_amount
What was approved, when the person narrowed it.
data.outcome, outcome_note
What the agent reported after acting.
data.url
The request in the inbox, when the server knows the website's address.

A denial by a rule, and a test:

{
  "id": "0196f1b8-0a1b-7c2d-8e3f-405162738495",
  "type": "request.denied",
  "timestamp": "2026-11-16T10:02:40.010203Z",
  "workspace_id": "0196f19c-1b2a-7e45-8d3c-6a7b9c0d1e2f",
  "data": {
    "request_id": "0196f1b8-0a00-7a11-b3e4-1a2b3c4d5e6f",
    "agent": "billing-bot",
    "action": "payment.refund",
    "summary": "Refund €900.00 to bo@example.com for order 1190",
    "amount": "900.00",
    "currency": "EUR",
    "status": "denied",
    "decided_by": "maya@northwind.example",
    "by_rule": true,
    "rule_id": "0196f150-9c8b-7a6d-9e5f-0a1b2c3d4e5f",
    "decision_note": "Refunds over €500 are never allowed",
    "changed": false,
    "approved_summary": null,
    "approved_amount": null,
    "…": "the other fields, as above"
  }
}
{
  "id": "0196f1c0-1111-7222-8333-444455556666",
  "type": "webhook.test",
  "timestamp": "2026-11-16T10:15:00.000000Z",
  "workspace_id": "0196f19c-1b2a-7e45-8d3c-6a7b9c0d1e2f",
  "data": {
    "endpoint_id": "0196f1c0-0000-7000-8000-000000000001",
    "message": "A test from VariantGate. Nothing happened to any request."
  }
}

Check the signature

Check every message before trusting it: that the signature matches, and that webhook-timestamp is within five minutes of now, so an old message cannot be sent again. Check the body exactly as it arrived, before any JSON parsing, since parsing and printing it again changes the bytes.

With the SDK

verifyWebhook in the TypeScript package and verify_webhook in the Python one do both checks, compare in constant time, and return the event. See SDK and command line to install them.

import { verifyWebhook, WebhookVerificationError } from "@variantgate/agent/webhook";

// A route in Next.js, Hono, Deno, Bun or a Cloudflare Worker.
export async function POST(request: Request) {
  const body = await request.text(); // the raw body, before any JSON parsing
  try {
    const event = await verifyWebhook(process.env.VARIANTGATE_WEBHOOK_SECRET!, request.headers, body);
    if (event.type === "request.approved") {
      await queue.send({ resume: event.data.request_id });
    }
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return new Response("bad signature", { status: 400 });
    }
    throw error;
  }
  return new Response(null, { status: 204 });
}
import os

from flask import Flask, request
from variantgate import WebhookVerificationError, verify_webhook

app = Flask(__name__)


@app.post("/variantgate")
def variantgate_webhook():
    try:
        event = verify_webhook(
            os.environ["VARIANTGATE_WEBHOOK_SECRET"],
            request.headers,
            request.get_data(),  # the raw body, before any JSON parsing
        )
    except WebhookVerificationError:
        return "", 400
    if event["type"] == "request.approved":
        queue.send({"resume": event["data"]["request_id"]})
    return "", 204

By hand in Node

The key is the base64 after whsec_. Sign {webhook-id}.{webhook-timestamp}.{body} with HMAC-SHA256 and compare it, in constant time, with each v1 signature in the header.

import { createHmac, timingSafeEqual } from "node:crypto";

const secret = process.env.VARIANTGATE_WEBHOOK_SECRET; // whsec_…

/** `headers` as Node gives them (lower-case names); `rawBody` as a string. */
export function verify(headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) {
    throw new Error("missing webhook headers");
  }
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 5 * 60) {
    throw new Error("timestamp too far from now");
  }
  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest();
  const matches = signatures.split(" ").some((entry) => {
    const [version, signature = ""] = entry.split(",");
    const given = Buffer.from(signature, "base64");
    return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected);
  });
  if (!matches) {
    throw new Error("no signature matches");
  }
  return JSON.parse(rawBody);
}

By hand in Python

import base64
import hashlib
import hmac
import json
import os
import time

SECRET = os.environ["VARIANTGATE_WEBHOOK_SECRET"]  # whsec_…


def verify(headers, raw_body: bytes) -> dict:
    """`headers` with lower-case names; `raw_body` exactly as it arrived."""
    msg_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > 5 * 60:
        raise ValueError("timestamp too far from now")
    key = base64.b64decode(SECRET.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
    for entry in headers["webhook-signature"].split():
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature.encode(), expected):
            return json.loads(raw_body)
    raise ValueError("no signature matches")

Read the request before acting

An event tells you to look, not to act. Whatever resumes the agent asks the API with the agent’s key, and the agent acts only on that answer:

# The agent, or whatever resumes it, asks with the agent key before acting.
curl https://api.variantgate.com/v1/requests/$REQUEST_ID \
  -H "authorization: Bearer $VARIANTGATE_KEY"
# Act only when the answer says "allowed": true.

With the SDK this is approvals.check(id) in TypeScript and client.check(id) in Python. See Requests for the answer’s fields.

Answers and retries

  • Answer with any 2xx status within 10 seconds. Do the work afterwards, on a queue: a slow answer counts as a failure.
  • Anything else, a timeout or no connection is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 8 hours: six attempts over about ten and a half hours, then it is given up.
  • Redirects are not followed. A 3xx answer counts as a failure, so give the final address.
  • Events can arrive twice, and out of order when one is retried. Drop an event whose webhook-id you have handled, and go by the request’s own status.
  • Your answer’s body is never read or kept. Settings shows the status code, or why there was none.
  • A receiver that is down never slows or fails the agent or the person deciding: events are sent on the side.

Turn off, rotate or remove

  • Turn off stops sending at once, including what was waiting to be tried again. Turn on starts again with the next event.
  • New secret makes a new signing secret and shows it once. The old one stops working at once, so update your receiver straight after.
  • Remove deletes the webhook and everything still queued for it.
  • Each of these, and adding a webhook, is kept in the record under Workspace changes, by label and host.

Limits

Plan
Pro and up. After moving to Free, existing webhooks keep working; new ones cannot be added.
Webhooks
At most 5 per workspace.
Address
At most 2,000 characters.
Label
1 to 100 characters.
Answer
Within 10 seconds, or it counts as a failure.
Kept
The last 50 deliveries of each webhook.

Which addresses are accepted

A webhook address is chosen by a customer, so the API makes sure it can never be pointed at its own network:

  • Only https, on the standard port, with no user name or password in the address.
  • A host name, never an IP address, and not a name kept for a private network such as localhost or .internal.
  • Every time it sends, the API looks the name up and refuses it if any address it leads to is not on the public internet: private and link-local ranges, the cloud metadata address, carrier-grade NAT, loopback, multicast, documentation and reserved ranges, in IPv4 and IPv6. It then connects only to the addresses it checked.