> ## 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.

# Threat Intel webhook

> Send structured vulnerability advisories and supply chain threats to Clarion via a signed webhook for AI-powered triage.

The **Threat Intel webhook** monitor accepts structured JSON payloads describing a vulnerability or a supply chain threat — for example a scanner posting a CVE finding or a malicious-package detection. Clarion turns each into an issue and triages it with AI agents.

<Note>
  **Estimated time:** 5 minutes. You will need a **Clarion workspace** and a sender that can sign requests with HMAC-SHA256.
</Note>

***

## Step 1 — Create the monitor

1. In Clarion, go to **Settings > Integrations**
2. Find **Threat Intel** and click **Add Monitor**
3. Pick the **Threat Intel** monitor type and give it a name
4. Click **Create**

Clarion generates a **webhook URL** and a **signing secret**. Copy both right away.

<Warning>
  Copy the signing secret immediately — it is only displayed once. You can regenerate it later from the monitor's Configure page, but you cannot view the current value.
</Warning>

***

## Step 2 — Send signed events

Point your sender at the webhook URL with an HTTP `POST`. The body must be a JSON **object** up to **100 KB**, signed with HMAC-SHA256.

* Compute `HMAC-SHA256(raw_request_body, signing_secret)` and send the **hex digest** in the `x-signature` header.
* The payload must contain a `vulnerability` object, a `threat` object, or both. Either one alone is enough.

**`vulnerability` fields**

| Field            | Required | Notes                                                            |
| ---------------- | -------- | ---------------------------------------------------------------- |
| `package`        | Yes      | Affected package name                                            |
| `currentVersion` | Yes      | Version in use                                                   |
| `fixedVersion`   | No       | Version that resolves the issue                                  |
| `advisory`       | No       | Advisory ID (e.g. a CVE or GHSA) — prefixed onto the issue title |
| `severity`       | No       | Drives the alert's severity (see mapping below)                  |

**`threat` fields**

| Field             | Required | Notes                                           |
| ----------------- | -------- | ----------------------------------------------- |
| `type`            | Yes      | Threat type (e.g. `malware`, `typosquat`)       |
| `package`         | Yes      | Affected package name                           |
| `detectedVersion` | No       | Version observed                                |
| `advisory`        | No       | Advisory reference                              |
| `severity`        | No       | Drives the alert's severity (see mapping below) |
| `indicator`       | No       | IOC / indicator string                          |

Any extra fields you include are preserved on the issue for the triage agent to reason about — nothing is dropped.

```bash theme={null}
SECRET="<signing-secret>"
BODY='{"vulnerability":{"package":"lodash","currentVersion":"4.17.20","fixedVersion":"4.17.21","advisory":"CVE-2021-23337","severity":"high"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl -X POST "https://<your-clarion-host>/api/webhooks/threat-intel/<monitor-id>" \
  -H "Content-Type: application/json" \
  -H "x-signature: $SIG" \
  -d "$BODY"
```

A successful request is accepted asynchronously (HTTP `202`); Clarion validates the payload and opens the issue on its worker. The issue title is derived from the payload — for example `CVE-2021-23337: Vulnerability in lodash@4.17.20` or `Supply chain threat: typosquat (left-pad@1.0.0)`.

***

## Severity mapping

The issue severity comes from the payload's `severity` string (the `vulnerability` value takes precedence over the `threat` value):

| Payload `severity`                     | Clarion severity |
| -------------------------------------- | ---------------- |
| `critical`                             | Critical         |
| `high`, `error`                        | High             |
| `medium`, `moderate`, `warning`        | Medium           |
| `low`, `info`, `informational`, `note` | Low              |
| *(missing or unrecognized)*            | High             |

***

## What happens next

Once configured, Clarion will automatically:

* Accept signed payloads at the monitor's webhook URL
* Open an issue for each vulnerability or threat, with the severity mapped above
* Triage incoming issues with AI agents and surface actionable insights

<Tip>
  Clarion ships a built-in **Threat Intelligence** agent that triages advisories and correlates them to your environment. Assign it to this monitor to automate the first pass.
</Tip>