> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript theme={null}
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

```python theme={null}
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)

```pseudo theme={null}
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

<CardGroup cols={3}>
  <Card title="Webhooks recipe" icon="webhook" href="/recipes/webhooks">
    Full pattern walkthrough.
  </Card>

  <Card title="Test webhook endpoint" icon="play" href="/api-reference/webhooks/test">
    Send a synthetic event to your handler.
  </Card>

  <Card title="Errors" icon="alert-triangle" href="/api-reference/errors">
    Error handling.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.