> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarion.cantina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Generic Webhook
> Send events from any service to Clarion via HTTP webhook for AI-powered triage and response.
This guide walks you through setting up a Clarion Generic Webhook monitor — a flexible endpoint that accepts JSON events from any service that can make an HTTP POST request. Use it to bring custom alerts, deploy events, CI failures, or any JSON payload into Clarion.
**Estimated time:** 5 minutes. You will need a **Clarion workspace** and the ability to configure outbound webhooks in the source service.
## Prerequisites
* A **Clarion workspace**
* A service that can send HTTP `POST` requests with a JSON body (CI systems, bespoke scripts, SaaS tools with webhook outputs, Slack-style senders, etc.)
***
## Step 1 — Create a Generic Webhook monitor
1. In Clarion, go to **Settings > Integrations**
2. Find **Webhook** and click **Add Monitor**
3. Give the monitor a **name** — it is prefixed onto alert titles, so different monitors are easy to tell apart
4. Pick an **authentication method** (see the next section)
5. Pick a **default severity** for issues opened by the monitor
6. Click **Create**
Clarion generates a **webhook URL** and, depending on the auth method, a **signing secret** or **bearer token**. Copy them right away.
Copy any generated secret immediately — it is only displayed once. You can rotate it later from the monitor's Configure page, but you cannot view the current value.
***
## Step 2 — Choose an authentication method
| Mode | How requests are authenticated | When to use |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **HMAC-SHA256 signature** | Sender signs the raw request body with the shared secret and sends the hex digest in `X-Webhook-Signature` (also accepts `X-Hub-Signature-256` with the `sha256=` prefix) | Production senders that can compute HMAC |
| **Bearer token** | Sender includes `Authorization: Bearer ` | Services with a simple token field in their webhook config |
| **No authentication** | Any request is accepted | Trusted internal networks only |
"No authentication" accepts any POST. Only use it for traffic that is already restricted by a private network or VPN.
The authentication method is fixed at creation. To switch, create a new monitor.
### Signature format
Some senders cannot put their signature in our header. With HMAC auth selected, the **Signature format** dropdown adds that sender's header to what the monitor accepts:
| Format | Also accepts |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **X-Webhook-Signature** (default) | nothing extra |
| **X-Payload-Digest** | `X-Payload-Digest`, with the algorithm named in `X-Payload-Digest-Alg`. Set the sender to SHA256 or SHA512 — the deprecated SHA1 option is refused |
| **Custom header** | the header you name, with the algorithm (SHA256/SHA512) and encoding (hex/base64) you pick |
Custom covers senders that sign the raw request body. A sender that signs a timestamp together with the body — Stripe and Slack do — will not verify against any of these; tell us and we will add it as a named format.
Unlike the authentication method, this can be changed at any time — it does not affect your secret.
***
## Step 3 — Send events from your service
Point the source service at the webhook URL Clarion gave you. Use `POST` with a JSON **object** body, up to 100 KB.
### Minimal example
```bash theme={null}
curl -X POST "https:///api/webhooks/generic-webhook/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{"type": "deploy.failed", "message": "Production deploy failed", "severity": "high"}'
```
### What goes in the payload
Any valid JSON object is accepted. Clarion looks at the payload's `type`, `event`, `eventType`, or `event_type` field (in that order) to derive an **event type** — used for matching filters and included in the issue title. If none of those fields is present, the event is treated as `generic`.
Fields used by the default alert template:
| Field | How it's used |
| --------------------------------------------- | -------------------------------------------------- |
| `type` / `event` / `eventType` / `event_type` | Event type — filter matching and alert title |
| `message` | Included as the body of the issue description |
| `severity` | Shown under "Reported severity" in the description |
| `source` | Shown under "Source" in the description |
All other fields are attached to the issue for reference — no field is dropped.
### Optional headers
| Header | Purpose |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `X-Webhook-Signature` or `X-Hub-Signature-256` | HMAC-SHA256 hex digest of the body (required when the monitor uses HMAC auth) |
| `X-Payload-Digest` | Only accepted when the monitor's signature format is set to **X-Payload-Digest** |
| `Authorization: Bearer ` | Required when the monitor uses Bearer auth |
| `X-Idempotency-Key` or `X-Request-Id` | If present, retries of the same value are treated as duplicates and will not create a second alert |
***
## The default "All webhook events" filter
When you create the monitor, Clarion adds an **All webhook events** filter that opens an issue for every incoming event with the default severity you chose. From the monitor's Configure page you can:
* **Change the default severity** — it applies to the default filter immediately
* **Disable** the default filter if you only want issues for specific events
* **Add more filters** that match by event type, payload fields, or conditions (e.g. only alert when `severity = critical`)
Each alert's title includes the monitor name and the time the event arrived; the description surfaces common payload fields (`message`, `severity`, `source`) alongside the event type.
***
## Using as a Slack replacement
Many services offer a "Slack incoming webhook URL" field for sending notifications. Because the Generic Webhook accepts arbitrary JSON, you can drop the Clarion webhook URL into those fields instead — your notifications become Clarion issues that get triaged by AI agents.
To set this up:
1. Create a Generic Webhook monitor with **No authentication** (most Slack-style senders don't sign requests) or **Bearer token** if the source service lets you add an `Authorization` header
2. Copy the webhook URL from the monitor
3. In the source service, paste the Clarion webhook URL wherever it asks for a Slack webhook URL
4. Send a test notification — it will appear as an issue in Clarion
Slack-compatible senders usually put the notification body in a `text` field, which isn't one of the event-type fields Clarion looks at — so those events are treated as `generic` and the default **All webhook events** filter still catches them.
For nicer alert titles, edit the default filter's title template to reference the fields your sender actually uses (for example `{{text}}` for Slack-style payloads).
***
## What happens next
Once configured, Clarion will automatically:
* Accept JSON events at the monitor's webhook URL
* Apply the default **All webhook events** filter (and any custom filters you add) to open issues
* Triage incoming issues using AI agents and surface actionable insights