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

# Webhooks

> Forensic webhook delivery system

AXON implements forensic webhooks through a durable outbox pattern with HMAC-signed delivery.

> [!NOTE]
>
> This is an advanced self-hosted/operator feature. Public launch does not yet include a dashboard UI for webhook configuration.

## Events

| Event | When |
| :- | :- |
| `decision.created` | New decision event recorded |
| `decision.denied` | Request denied by policy or risk |
| `decision.escalated` | Request escalated for human approval |
| `payment.settled` | Payment successfully settled on-chain |

## Delivery Model

1. Decision flow enqueues events for matching org webhook configs
2. Dispatcher claims a batch via RPC (`claim_event_outbox_batch`) using row locks
3. Each claimed row increments `attempts` and gets a short lease
4. Successful delivery marks row `delivered`
5. Failed delivery marks row `retrying` (or `dead_letter` at max attempts)

## Payload Format

```json theme={null}
{
  "id": "<outbox-id>",
  "event": "decision.created",
  "payload": {
    "spend_request_id": "...",
    "decision_id": "..."
  },
  "timestamp": "2026-02-22T00:00:00.000Z"
}
```

### Headers

```
Content-Type: application/json
X-AXON-SIGNATURE: <hex hmac sha256>
X-AXON-SIGNATURE-ALG: hmac-sha256
```

## Manual Dispatch

Requires the static operator bearer `AXON_DECISION_API_KEY`.

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $AXON_DECISION_API_KEY" \
  "http://127.0.0.1:3030/v1/webhooks/dispatch"
```

Returns delivered and failed counts.

## Configuration

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_FORENSIC_WEBHOOKS_ENABLED` | `true` | Enable webhook delivery |
| `AXON_WEBHOOK_WORKER_INTERVAL_MS` | `10000` | Dispatch interval |
| `AXON_WEBHOOK_TIMEOUT_MS` | `8000` | Per-delivery timeout |
| `AXON_WEBHOOK_MAX_ATTEMPTS` | `6` | Max delivery attempts before dead-letter |
| `AXON_WEBHOOK_CLAIM_LEASE_SECONDS` | `30` | Lease duration for batch claims |

> [!NOTE]
>
> Dashboard webhook configuration UI is not implemented. Today, webhook configs are managed directly in the `webhook_configs` table.

## SSRF Protection

AXON validates webhook URLs at dispatch time to prevent server-side request forgery.

**Blocked destinations:**

* Private IPv4 ranges: `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`
* Private IPv6 addresses: `::1`, `fe80::`, `fc00::`, `fd00::`
* HTTPS is required in production (HTTP is only permitted in development)

**Retry backoff:**

Failed deliveries use exponential backoff capped at 5 minutes:

```
delay = min(300000, 1000 * 2^attempts)
```

| Attempt | Delay |
| :- | :- |
| 1 | 2 s |
| 2 | 4 s |
| 3 | 8 s |
| 4 | 16 s |
| 5 | 32 s |
| 6+ | 5 min (cap) |


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