> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.veilio.xyz/documentation/webhooks/siem-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.