Webhooks SDK helpers

Signature verification helpers for handling vly webhooks securely in every supported language.

vly’s webhook events are signed using HMAC-SHA256. Verify the signature before processing — otherwise, your endpoint is exposed to anyone who can reach it.

TypeScript

import { verifyWebhook } from "@vly/sdk";

export async function POST(req: Request) {
  const body = await req.text();
  const sig  = req.headers.get("x-vly-signature");

  try {
    const event = verifyWebhook(body, sig, process.env.VLY_WEBHOOK_SECRET!);
    // event.type, event.data
    return new Response(null, { status: 200 });
  } catch {
    return new Response("Bad signature", { status: 400 });
  }
}

Python

from vly.webhooks import verify_webhook

@app.post("/webhook")
def webhook(request):
    body = request.body
    sig  = request.headers.get("x-vly-signature")
    try:
        event = verify_webhook(body, sig, os.environ["VLY_WEBHOOK_SECRET"])
        # event.type, event.data
        return Response(status=200)
    except Exception:
        return Response("Bad signature", status=400)

Manual verification (any language)

expected = "sha256=" + hmac_sha256(secret, raw_body).hex()
if not constant_time_compare(expected, signature_header):
    reject

Always use constant-time comparison to prevent timing attacks.

Available events

Event	When
project.created	A new project is created
project.deleted	A project is deleted
deployment.succeeded	A deployment completes successfully
deployment.failed	A deployment fails
agent.completed	An agent run completes
agent.failed	An agent run fails
billing.usage_threshold	Workspace crosses a usage threshold

Registering endpoints

Workspace settings → Webhooks → Add endpoint. Pick the events you want, paste your URL, copy the signing secret.

Related

Webhooks recipe

Full pattern walkthrough.

Test webhook endpoint

Send a synthetic event to your handler.

Errors

Error handling.