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

# Webhooks

> Three endpoints to register webhooks, receive real-time score change notifications, and replay missed deliveries from the Axiom Locus event stream.

## `POST` `/api/v1/webhooks`

<Note>Requires Bearer token.</Note>

Register a webhook to receive real-time notifications when scores change, new permits are filed, or monitored locations trigger alerts.

**Request body**

```json theme={null}
{
  "url": "https://your-app.com/hooks/axiom",
  "events": ["score.changed", "permit.filed", "alert.triggered"],
  "secret": "whsec_your_signing_secret"
}
```

| Field    | Type   | Required | Default | Description                                                                           |
| -------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------- |
| `url`    | string | ✓        |         | HTTPS endpoint to receive webhook POST requests.                                      |
| `events` | array  | ✓        |         | Events to subscribe to: score.changed, permit.filed, alert.triggered, monitor.report. |
| `secret` | string |          |         | Signing secret for HMAC-SHA256 payload verification.                                  |

**Example**

```bash theme={null}
curl -X POST "https://axiomlocus.io/api/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{"url":"https://your-app.com/hooks/axiom","events":["score.changed","permit.filed"]}'
```

**Response**

```json theme={null}
{
  "webhook": {
    "id": "wh_abc123def456",
    "url": "https://your-app.com/hooks/axiom",
    "events": ["score.changed", "permit.filed"],
    "active": true,
    "created_at": "2026-03-31T12:00:00Z"
  }
}
```

| Field            | Type    | Description                                |
| ---------------- | ------- | ------------------------------------------ |
| `webhook.id`     | string  | Unique webhook identifier (prefixed wh\_). |
| `webhook.events` | array   | Subscribed event types.                    |
| `webhook.active` | boolean | Whether the webhook is currently active.   |

## `GET` `/api/v1/webhooks`

<Note>Requires Bearer token.</Note>

List all registered webhooks for your account.

**Example**

```bash theme={null}
curl "https://axiomlocus.io/api/v1/webhooks" \
  -H "Authorization: Bearer al_your_key_here"
```

**Response**

```json theme={null}
{
  "webhooks": [
    {
      "id": "wh_abc123def456",
      "url": "https://your-app.com/hooks/axiom",
      "events": ["score.changed", "permit.filed"],
      "active": true,
      "created_at": "2026-03-31T12:00:00Z",
      "last_delivery": "2026-03-31T14:22:00Z",
      "delivery_success_rate": 0.98
    }
  ]
}
```

| Field                              | Type   | Description                              |
| ---------------------------------- | ------ | ---------------------------------------- |
| `webhooks`                         | array  | All registered webhook objects.          |
| `webhooks[].delivery_success_rate` | float  | Success rate of recent deliveries (0-1). |
| `webhooks[].last_delivery`         | string | Timestamp of last delivery attempt.      |

## `DELETE` `/api/v1/webhooks`

<Note>Requires Bearer token.</Note>

Delete a webhook registration.

**Query parameters**

| Name | Type   | Required | Default | Description                 |
| ---- | ------ | -------- | ------- | --------------------------- |
| `id` | string | ✓        |         | Webhook ID (prefixed wh\_). |

**Example**

```bash theme={null}
curl -X DELETE "https://axiomlocus.io/api/v1/webhooks?id=wh_abc123def456" \
  -H "Authorization: Bearer al_your_key_here"
```

**Response**

```json theme={null}
{ "success": true }
```

| Field     | Type    | Description                                   |
| --------- | ------- | --------------------------------------------- |
| `success` | boolean | Whether the webhook was successfully deleted. |