> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks & Billing Events

> Operating the webhook endpoints platform on a self-hosted deployment, egress policy, local receivers, the license flag, and billing settlement tuning.

The [webhook endpoints platform](/docs/features/webhooks) and the [billing events surface](/docs/ai-gateway/billing-events) run unchanged on self-hosted deployments. This page covers what the operator controls: the license flag, the outbound egress policy, local receivers for development and internal networks, and billing settlement tuning.

## License

Webhook endpoints and the billing pull APIs are gated by the `webhookEndpointsEnabled` flag on your enterprise license. Without it, the REST surfaces answer `403`, delivery does not register, and **Settings > Webhooks** shows the upgrade state. Adding the license to a running deployment lights the surfaces up without a migration, the same flow as every enterprise flag (see [Compliance](/docs/self-hosting/compliance)).

## Outbound egress and SSRF policy

Webhook URLs are customer-supplied and fired from your control-plane workers, so the sender is fenced:

* **HTTPS only.** Plain `http://` URLs are rejected at save time.
* **Private and loopback addresses are always blocked**, including IP literals and bracketed IPv6, regardless of the deployment-wide `BLOCK_LOCAL_HTTP_CALLS` setting. A delivery must never reach `10.x`, `192.168.x`, `localhost`, or link-local addresses.
* **Redirects are never followed.** A `3xx` from a receiver is a terminal delivery failure, not a hop.
* Response sizes and timeouts are capped; the receiver's status, latency, and a response excerpt land in the delivery log.

If your network requires an egress allowlist at the firewall, the platform's deliveries originate from the control-plane worker pods; route them like any other outbound HTTPS from those pods.

## Local and internal receivers

Development setups and some internal architectures legitimately need receivers on private addresses. The escape hatch:

```
WEBHOOKS_UNSAFE_ALLOW_LOCAL_URLS=1
```

With the flag set, endpoint URLs may use `http://` and resolve to private or loopback addresses. **Only** the local-address fence is relaxed: size caps, timeouts, no-redirects, and signing all stay in force. Leave this unset in production unless your receivers are deliberately internal; it is the difference between "our workers can only call out" and "our workers can reach anything on the pod network".

## Authentication model

Webhook and billing REST surfaces authenticate with an **organization API key** and organization-tier permissions (`webhookEndpoints:view|manage`, `gatewaySpend:view|manage`). These permissions are organization-exclusive: a team- or project-scoped role binding can never grant them, so a project-level credential cannot register an endpoint that streams org-wide events out. Grant them through org roles or a custom org-scoped role; see [RBAC](/docs/ai-gateway/rbac).

## Billing settlement window

A gateway request that was admitted but never confirmed is settled after a grace window and delivered as `gateway.request.settled` with unknown cost (see [settled semantics](/docs/ai-gateway/billing-events#settled-events-and-supersession)). The default grace is **30 minutes**. Tune it with:

```
LW_SPEND_SETTLEMENT_GRACE_MS=1800000
```

Shorter windows surface stuck requests to your billing sooner but settle more requests that were merely slow; a later confirmation always supersedes the settled event either way, so the trade is about how much churn your settled work queue sees, not about correctness.

## Retention

* **Spend records**: fixed 13 months, declared in the table's own migration, deliberately outside both tenant retention policies and the cold-storage TTL reconciler. Do not add `gateway_spend` to retention configs; a unit test pins the exemption.
* **Delivery log**: 30 days, matching the automations webhook log.

## See also

* [Webhooks](/docs/features/webhooks): the platform reference.
* [Billing & spend events](/docs/ai-gateway/billing-events): the money contract and reconciliation.
* [Data retention](/docs/platform/data-retention): tenant retention and the billing exemption.
* [Self-hosting security](/docs/self-hosting/security): network boundaries and secrets.