# Sending Incode Events to Splunk

[Splunk](https://splunk.com/) is a widely adopted Security Information and Event Management (SIEM) platform used for log aggregation, threat detection, and operational analytics. Incode's event system is built on webhooks — HTTP callbacks that push real-time notifications to your infrastructure whenever a key identity verification event occurs. Since Splunk's HTTP Event Collector (HEC) is designed to accept inbound HTTP payloads, the two systems connect naturally.

This guide walks through everything you need to get Incode identity events flowing into Splunk for centralized visibility and analysis.

The instructions below are written for Splunk Cloud. If you're running Splunk Enterprise, the process is largely the same.

---

## Table of Contents

- [Splunk Configuration](https://workforce.developer.incode.com/docs/splunk-integration#splunk-configuration)
- [Incode Configuration](https://workforce.developer.incode.com/docs/splunk-integration#incode-configuration)
- [Webhook Events Reference](https://workforce.developer.incode.com/docs/splunk-integration#webhook-events-reference)
- [Webhook Payload Format](https://workforce.developer.incode.com/docs/splunk-integration#webhook-payload-format)

---

## Splunk Configuration

Before touching anything in Incode, you'll need to set up an HTTP Event Collector (HEC) token in Splunk. This is what allows Splunk to receive incoming JSON payloads over HTTP.

### Step 1 — Navigate to Data Inputs

In Splunk, open the **Settings** menu and choose **Data inputs**.

### Step 2 — Open HTTP Event Collector

From the **Data inputs** page, select **HTTP Event Collector** to manage your HEC tokens.

### Step 3 — Create a New Token

Click **New Token** and fill in the form as follows:

| Field | Suggested Value |
| --- | --- |
| Name | `Incode` |
| Source name override | `incode` |
| Description | `Identity verification events from Incode` |
| Enable indexer acknowledgement | Leave unchecked |

Click **Next** to continue.

### Step 4 — Finalize and Save

On the **Input Settings** screen, the defaults are fine — click **Review**, then **Submit**. Your new HEC token will be shown on the confirmation screen. **Copy it now** and store it somewhere accessible; you'll need it when configuring Incode.

You can always retrieve the token again from **Settings → Data inputs → HTTP Event Collector** if needed.

---

## Incode Configuration

With your HEC token in hand, head to the Incode Dashboard and go to **Configuration → Webhooks**. This is where you'll tell Incode where to send event data. The full webhook reference is available at [developer.incode.com/docs/webhooks](https://developer.incode.com/docs/webhooks).

### Step 1 — Enter the Splunk Endpoint

In the **URL** field, enter your Splunk HEC endpoint:

```undefined
https://<HOST>.splunkcloud.com:8088/services/collector/raw
```

Replace `<HOST>` with your Splunk Cloud collection hostname.

Two things to note about this URL:

- **`/services/collector/raw` not `/services/collector/event`** — Incode sends plain JSON payloads with no wrapper or envelope. The `/event` endpoint expects payloads wrapped in Splunk's own JSON format, so using it will cause Splunk to fail to parse the data and drop events. `/raw` accepts the payload exactly as Incode sends it.

### Step 2 — Add the HEC Token as a Custom Header

Splunk's HEC endpoint requires a token to accept incoming data. The correct way to pass it is via the **Webhook Custom Headers** section in the Incode Dashboard — leave the Authentication section above it blank, as that is for OAuth2 and is not applicable here.

Add the following header:

| Header Name | Value |
| --- | --- |
| `Authorization` | `Splunk <HEC_TOKEN>` |

Replace `<HEC_TOKEN>` with the token you copied from Splunk.

### Step 3 — Choose Which Events to Send

Select the webhook events you want Incode to forward to Splunk. See the [Webhook Events Reference](https://workforce.developer.incode.com/docs/splunk-integration#webhook-events-reference) section below for a complete breakdown of what each event represents.

A practical starting point for most SIEM use cases — covering final outcomes without exposing PII:

- `ONBOARDING_FINISHED`
- `SESSION_SUCCEEDED`
- `SESSION_FAILED`
- `SESSION_PENDING_REVIEW`

If you need more granular visibility into in-progress verification steps — and your data handling policies permit it — you can also enable intermediate events that may carry PII:

- `ID_VALIDATION_FINISHED`
- `GOVERNMENT_VALIDATION_FINISHED`
- `FACE_VALIDATION_FINISHED`

### Step 4 — Additional Custom Headers (Optional)

Beyond the `Authorization` header added in Step 2, you can define additional static headers that get attached to every outbound webhook request. These are useful for internal routing tokens or any other fixed header value your infrastructure requires.

Keep in mind that all headers you define will be sent across all webhook types — there's no per-event header customization, and dynamic values aren't supported.

---

## Webhook Events Reference

Incode's webhook system spans several categories, each covering a different aspect of the identity verification lifecycle. All events arrive as `HTTP POST` requests with a JSON body.

### Onboarding Status Events

The **Onboarding Status Webhook** emits a notification each time the processing state of a verification session advances. Because a full onboarding session involves multiple modules — ID capture, government validation, face match, and more — this webhook can fire several times per session in sequence.

| Event | When It Fires | May Contain PII? |
| --- | --- | --- |
| `ID_VALIDATION_FINISHED` | Document capture and validation modules have completed. OCR data and ID scores are accessible at this point, though the session isn't done yet. | Yes |
| `ID_VALIDATION_FINISHED_SECOND_ID` | Same as above but for a second ID document, when applicable. | Yes |
| `GOVERNMENT_VALIDATION_FINISHED` | The government records check has completed. Preliminary data is available via the API, but waiting for `ONBOARDING_FINISHED` is recommended for finalized results. | Yes |
| `FACE_VALIDATION_FINISHED` | The liveness check and face-to-ID comparison have finished. This fires after both the ID and selfie steps are complete. | Yes |
| `POST_PROCESSING_FINISHED` | All collected session data has been fully processed. | No |
| `POST_PROCESSING_FINISHED_SECOND_ID` | Post-processing complete for the second ID document, if one was collected. | No |
| `ONBOARDING_FINISHED` | The session has reached a final determination. All data is processed, custom business rules have been evaluated, the user has exited the flow, and a final session status has been assigned. **This is the recommended event for triggering downstream actions.** | No |
| `MANUAL_REVIEW_APPROVED` | A session that was in a `MANUAL` review state has been approved by an analyst in the Incode Dashboard. | No |
| `MANUAL_REVIEW_REJECTED` | A session that was in a `MANUAL` review state has been rejected by an analyst in the Incode Dashboard. | No |
| `EXPIRED` | The user abandoned the session and the configured expiration window elapsed. When the user attempts to return, they'll see an expiration screen. | No |
| `DELETED` | Session data has been removed. This payload uses `interviewIds` (an array) instead of the usual `interviewId` field, since multiple sessions may be deleted in a single operation. | No |

### Session Webhooks

Session webhooks give you a clean, one-notification-per-outcome model. Each of the four events below can be pointed at its own URL, and each fires exactly once per session when that specific outcome occurs.

| Event | Description |
| --- | --- |
| `SESSION_STARTED` | The end user has entered the verification flow and begun the session. |
| `SESSION_FAILED` | The session concluded with a failure — the user did not pass verification. |
| `SESSION_SUCCEEDED` | The session concluded successfully — the user passed verification. |
| `SESSION_PENDING_REVIEW` | The session requires human review before a final outcome can be assigned. |

## Webhook Payload Format

### Onboarding Status — Sample Payload

JSON

```json
{
  "clientId": "MyClientId001",
  "flowId": "66969519eb1d789a96347ca7",
  "interviewId": "664283755e0f8e1b87fcc2ce",
  "externalCustomerId": "MyCustomerID#0001",
  "onboardingStatus": "ONBOARDING_FINISHED"
}
```

### Session Webhook — Common Payload Fields

All four session webhooks share a common set of fields:

| Field | Type | Description |
| --- | --- | --- |
| `event_type` | `string` | The webhook event name: `SESSION_STARTED`, `SESSION_FAILED`, `SESSION_SUCCEEDED`, or `SESSION_PENDING_REVIEW` |
| `timestamp` | `string` | UTC timestamp of the event in ISO 8601 format |
| `interviewId` | `string` | Unique identifier for the session |
| `externalCustomerId` | `string` | Your system's identifier for the user, used for data matching |
| `clientId` | `string` | Your organization's unique identifier |
| `configurationId` | `string` | Identifier for the Flow or Workflow that triggered the session |

Additional fields are included in `SESSION_FAILED`, `SESSION_SUCCEEDED`, and `SESSION_PENDING_REVIEW`:

| Field | Type | Description |
| --- | --- | --- |
| `onboardingStatus` | `string` | Always `ONBOARDING_FINISHED` for these events |
| `ip` | `string` | End user device IP from the device fingerprint (not available for API-only sessions) |
| `latitude` / `longitude` | `string` | Device location at the time of the session (not available for API-only sessions) |

`SESSION_SUCCEEDED` also includes:

| Field | Type | Description |
| --- | --- | --- |
| `identityId` | `string` | Unique identifier for the Identity that was matched or created for this session |

### How to Respond

Incode expects one of the following HTTP responses from your endpoint to mark a delivery as successful:

- `204 No Content`
- `200 OK` with `Content-Type: application/json`

Example of an acceptable `200` response body:

JSON

```json
{ "success": true }
```

Returning anything else, or timing out, will trigger a retry.

---

## Additional Resources

- [Incode Webhooks Overview](https://developer.incode.com/docs/webhooks)
- [Authenticating Webhook Requests](https://developer.incode.com/docs/authenticating-webhooks-requests)
- [Onboarding Status Webhook Reference](https://developer.incode.com/docs/onboarding-status-webhook)
- [Session Webhooks Reference](https://developer.incode.com/docs/session-webhooks)
- [Incode Dashboard](https://dashboard.incode.com/)
- [Splunk HEC Documentation](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector)