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

# Webhooks

> Send security alert payloads to any HTTP endpoint

Alert webhooks let you forward Charley security events to any HTTP endpoint — your SIEM, PagerDuty, a custom Lambda, or anything else that accepts a POST request.

## Adding a Webhook

1. Go to **Settings** → **Alert Webhooks**.
2. Click **Add Endpoint**.
3. Enter the destination URL.
4. Optionally add a description.
5. Click **Save**.

Charley will immediately send a test ping to verify the endpoint is reachable.

## Payload Format

Charley sends an HTTP `POST` with a JSON body:

```json theme={null}
{
  "event": "threat.blocked",
  "org_id": "org_01hx...",
  "device_id": "dev_01hx...",
  "timestamp": "2025-10-14T18:32:00Z",
  "data": {
    "url": "https://example-malicious.com",
    "classification": "malware",
    "risk_score": 0.98
  }
}
```

### Event Types

| Event             | Description                             |
| ----------------- | --------------------------------------- |
| `threat.blocked`  | Agent blocked a malicious URL           |
| `threat.warned`   | Agent warned the user about a risky URL |
| `device.disabled` | A device was disabled by an admin       |
| `device.enrolled` | A new device was enrolled               |
| `billing.failed`  | A payment failed                        |

## Retries

If your endpoint returns a non-2xx response, Charley retries the delivery up to **3 times** with exponential backoff (1 min, 5 min, 15 min).

Failed deliveries appear in the webhook log accessible from the endpoint detail view.

## Securing Your Endpoint

Charley does not currently sign webhook payloads with a secret. To secure your endpoint:

* Restrict it to Charley's IP ranges (contact support for the current list)
* Place it behind an API gateway with key authentication

## Deleting a Webhook

Go to **Settings** → **Alert Webhooks**, click the action menu on the endpoint, and select **Delete**. Charley stops sending events to that URL immediately.