> For the complete documentation index, see [llms.txt](https://docs.veilio.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veilio.xyz/documentation/webhooks/siem-integration.md).

# SIEM Integration

Veilio pushes real-time audit events to your SIEM or security stack. Veilio does not replace your SIEM — it feeds it.

#### Who is this for?

* Security teams (CISO, SOC) monitoring tokenization and detokenization
* Compliance / DPO teams needing centralized audit trails
* Enterprise customers on Splunk, Microsoft Sentinel, QRadar, Elastic, or custom collectors

Enterprise plan required (or on-premise deployment).

***

#### Setup (dashboard)

1. Sign in as the **organization Owner**.
2. Open **Dashboard → Webhooks**.
3. Choose **Generic webhook** or **Splunk HEC**.
4. Enter your HTTPS collector URL.
5. Select **event filters** (which `event_type` values to forward).
6. **Create** — copy the signing secret (generic webhook only; shown once).
7. Click **Test** to send a `SIEM_TEST` event.

***

#### Event payload

```json
{
  "event_id": "evt_...",
  "timestamp": "2026-07-03T10:00:00.000Z",
  "source": "veilio",
  "event_type": "DETOKENIZE",
  "severity": "high",
  "organization_id": "org_...",
  "actor": {
    "user_id": "...",
    "api_key_id": "...",
    "ip_address": "...",
    "user_agent": "..."
  },
  "resource": {
    "token_id": "tok_...",
    "token_type": "email"
  },
  "outcome": "success",
  "reason": "Support ticket resolution",
  "error": null
}
```

No plaintext PII is ever included in SIEM payloads.

***

#### Event type catalogue

Configure which events to forward per destination. All types below are available as dashboard filters.

| `event_type`     | Severity | When emitted                           |
| ---------------- | -------- | -------------------------------------- |
| `TOKENIZE`       | medium   | A new token is created                 |
| `DETOKENIZE`     | **high** | Plaintext is revealed via detokenize   |
| `SHRED`          | **high** | A token is cryptographically destroyed |
| `API_KEY_CREATE` | **high** | A new API key is created               |
| `API_KEY_DELETE` | **high** | An API key is revoked or deleted       |
| `USER_CREATE`    | medium   | A new user account is created          |
| `USER_UPDATE`    | medium   | User profile or settings updated       |
| `USER_LOGIN`     | medium   | Successful dashboard login             |
| `SIEM_TEST`      | low      | Manual test from Webhooks dashboard    |

**Recommended filters for SOC**

| Use case                     | Filter                             |
| ---------------------------- | ---------------------------------- |
| Data exfiltration monitoring | `DETOKENIZE`, `SHRED`              |
| Credential / key hygiene     | `API_KEY_CREATE`, `API_KEY_DELETE` |
| Access anomalies             | `USER_LOGIN`, `DETOKENIZE`         |
| Full audit trail             | All event types                    |

***

#### Signature verification (generic webhook)

**Header:** `X-Veilio-Signature: t=<unix_timestamp>,v1=<hmac_sha256_hex>`

**Signed string:** `<unix_timestamp>.<raw_json_body>`

**Verification steps**

1. Parse `t` and `v1` from the header.
2. Reject if `t` is older than 5 minutes (replay protection).
3. Compute `HMAC-SHA256(secret, t + "." + rawBody)` as hex.
4. Compare with `v1` using a constant-time comparison.

**Node.js example**

```js
import crypto from "crypto";

function verifyVeilioSignature(secret, rawBody, header) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.trim().split("="))
  );
  const t = parts.t;
  const v1 = parts.v1;
  if (!t || !v1) return false;
  if (Date.now() / 1000 - Number(t) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}
```

***

#### Splunk HEC

* **URL:** `https://<host>:8088/services/collector/event`
* Provide your HEC token in the Veilio form.
* Optional: Splunk index and sourcetype (`_json` by default).
* **Authorization header:** `Splunk <token>`

***

#### Common SIEM mappings

| Platform                 | Approach                                                                           |
| ------------------------ | ---------------------------------------------------------------------------------- |
| **Splunk**               | Use **Splunk HEC** destination type in Veilio                                      |
| **Microsoft Sentinel**   | Logic App or Azure Function behind generic webhook → map `event_type` to incidents |
| **QRadar**               | Custom HTTPS log source → parse JSON, use `event_type` as category                 |
| **Elastic / OpenSearch** | Ingest pipeline on generic webhook; index by `organization_id` + `event_type`      |
| **Palo Alto XSOAR**      | Webhook integration → incident mapping on `DETOKENIZE` + `SHRED`                   |

**Sentinel quick pattern**

1. Create a Logic App with **When a HTTP request is received**.
2. Paste the URL into Veilio generic webhook.
3. Filter on `event_type == "DETOKENIZE"` for high-severity alerts.
4. Forward to Sentinel via the built-in connector.

***

#### Reliability and delivery log

* Async delivery with **3 retries** (0s, 2s, 8s backoff)
* **10s** HTTP timeout per attempt
* Delivery status visible in **Dashboard → Webhooks** (per destination)
* Failed deliveries include `outcome: "failure"` and `error` in the payload when applicable

**Idempotency:** use `event_id` as a deduplication key in your SIEM — Veilio generates a unique ID per event.

***

#### Related links

* Security Best Practices
* Troubleshooting