# Webhooks

Canonical: https://auggy.dev/docs/webhooks
Status: Preview
Package: auggy 0.5.0

Advanced preview: handle provider callbacks through focused augment routes with deterministic signature checks.

## Purpose

> **Note: Advanced preview**
>
> Webhook routes are an optional integration surface. Existing application webhook handlers can continue to own provider callbacks and invoke narrow agent tools or notifications only when needed.

Webhooks are provider infrastructure, not chat turns. Verify and handle routine callbacks in code; notify the operator when they fail.

## Current support

- Webhook signature policy metadata on route definitions.
- Runtime Stripe and Svix signature verification before the handler runs.
- Webhook policy routes are omitted from browser generated clients.
- Svix verification checks the raw body, signature envelope, delivery ID, and timestamp age before the handler runs.

## Pattern

**Provider callback route**

```ts
import { defineRoute, webhook } from "auggy";

defineRoute.post("/webhooks/stripe", {
  auth: "none",
  maxBodyBytes: 64_000,
  policy: webhook.signature("stripe", { secretEnv: "STRIPE_WEBHOOK_SECRET" }),
  handler: async ({ webhook: verified }) => {
    await applyBillingEvent(verified?.event);
    return new Response("ok");
  },
});
```

For a Svix-signed provider, use `webhook.signature("svix", { secretEnv: "PROVIDER_WEBHOOK_SECRET" })`. AgentMail inbound mounts this policy at `/webhooks/agentmail` and then applies its own inbox, sender, classification, dedup, and turn-admission rules.

> **Warning: Do not model-verify webhooks**
>
> Verify provider signatures in code. Do not ask the model whether a callback is valid.

## Related

- [Add HTTP routes](https://auggy.dev/docs/add-http-routes/markdown)
- [Delegated authorization](https://auggy.dev/docs/delegated-authorization/markdown)
- [Logs and recovery](https://auggy.dev/docs/logs-and-recovery/markdown)