# Webhook Integration
StepSecurity's Webhook Integration enables you to receive real-time notifications about security events detected in your organization
This allows teams to respond quickly, integrate with incident response workflows, and enhance observability across CI/CD pipelines.
### Prerequisites
Before setting up the Webhook integration:
* You must be an **Admin** in your StepSecurity organization.
* You should have a webhook endpoint ready to receive `POST` requests.
* The endpoint must support HTTPS and accept JSON payloads.
### Setup
**Step 1: Navigate to your StepSecurity dashboard**
**Step 2: Click "Admin console"**
**Step 3: Click "Integrations"**
**Step 4: Click "Enable Webhook Integration**
**Step 5: Configure Webhook Integration**
* Enter your Webhook URL in the corresponding input field.
* Select the HTTP Method (e.g., POST or GET) from the dropdown.
* Add headers such as Authorization, Content-Type, etc.
* For example, set Content-Type to application/json.
* Click “+ Add Header” to add multiple headers if needed.
* Choose your message format from the dropdown:
* Raw – sends raw event data
* Envelope – wraps the event data in an envelope structure. (You can select from various template variables)
* Select the kind of content to send:
* Toggle on Send Insights and/or Send Detections as required.
* Click “Test Connection” to validate the webhook setup.
**Step 6: Select the Repos you want to send webhook events for**
**Step 7: Click “Save changes” to apply your configuration**
### Webhook Delivery
Once configured, StepSecurity sends detection alerts to your endpoint as HTTP `POST` requests containing JSON payloads.
#### How Delivery Works
* Each webhook is sent as a **single HTTP POST request** with `Content-Type: application/json`.
* The entire JSON payload is contained within one HTTP request body.
* Each request represents **one workflow run** that triggered one or more detections.
* Multiple detections from the same workflow run are bundled together in a single payload inside the `data` array.
#### Payload Structure
Each webhook payload follows a parent-child structure. The top-level object contains metadata about the alert group, and the `data` array contains individual detection objects.
| Field | Type | Description |
| ----------------- | -------- | -------------------------------------------------------- |
| `id` | UUID | Unique identifier for this alert group (parent ID) |
| `name` | String | Human-readable summary of the alert group |
| `alert_timestamp` | ISO 8601 | Timestamp when the alert was generated |
| `event_type` | String | Type of event (e.g., `"detection"`) |
| `customer` | String | Customer account identifier |
| `owner` | String | GitHub organization or owner name |
| `repo` | String | Repository name |
| `repository` | String | Full repository path (`owner/repo`) |
| `run_id` | String | GitHub Actions workflow run ID |
| `data` | Array | Array of individual detection objects (see next section) |
**Example top-level payload:**
json
```json
{
"id": "81d3597b-b8ca-4ac1-abf0-cc7a9961714d",
"name": "Detections for workflow run 98765",
"alert_timestamp": "2025-02-20T14:30:00Z",
"event_type": "detection",
"customer": "acme-corp",
"owner": "acme",
"repo": "api-service",
"repository": "acme/api-service",
"run_id": "98765",
"data": [
{ "...detection object 1..." },
{ "...detection object 2..." }
]
}
```
#### Parent-Child Correlation
Every webhook payload has a top-level `id` field that serves as the **parent identifier**. Each detection object within the `data` array includes a `parent_id` field that references this top-level `id`. This allows you to correlate all detections that originated from the same workflow run.
```
Top-level: "id": "81d3597b-b8ca-4ac1-abf0-cc7a9961714d"
Detection: "parent_id": "81d3597b-b8ca-4ac1-abf0-cc7a9961714d"
```
### Detection Object Fields
Each object in the `data` array represents an individual detection. The following fields are common across all detection types:
| Field | Type | Description |
| ---------------- | ---------- | --------------------------------------------------- |
| `id` | String | Detection type identifier (e.g., `"Reverse-Shell"`) |
| `event_id` | UUID | Unique ID for this specific detection event |
| `parent_id` | UUID | References the top-level alert group `id` |
| `type` | String | Detection type classification |
| `name` | String | Human-readable detection name |
| `run_id` | String | GitHub Actions run ID |
| `job_id` | String | GitHub Actions job ID |
| `job` | String | Job name within the workflow |
| `timestamp` | Unix epoch | Detection timestamp (seconds since epoch) |
| `detection` | String | Detection signature identifier |
| `html_url` | URL | Link to the detection in StepSecurity dashboard |
| `is_resolved` | Boolean | Whether the detection has been resolved |
| `is_suppressed` | Boolean | Whether the detection is suppressed |
| `process_events` | Array | Process-level details (varies by detection type) |
**Example detection object:**
json
```json
{
"id": "Reverse-Shell",
"event_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"parent_id": "81d3597b-b8ca-4ac1-abf0-cc7a9961714d",
"type": "network",
"name": "Reverse Shell Detected",
"run_id": "98765",
"job_id": "build-and-test",
"job": "Build and Test",
"timestamp": 1740062400,
"detection": "reverse_shell_v2",
"html_url": "https://app.stepsecurity.io/detections/f47ac10b-58cc-4372-a567-0e02b2c3d479",
"is_resolved": false,
"is_suppressed": false,
"process_events": []
}
```
> For complete payload examples with real-world detection data, see [Sample Detection Events](/administration/admin-console/integrations/sample-detection-events.md).
***
### SIEM Integration
If you are forwarding StepSecurity webhooks to a SIEM (e.g., Splunk, Microsoft Sentinel, Elastic), follow these guidelines to ensure alerts are ingested correctly.
#### Toggling Insights and Detections
When configuring webhooks for SIEM ingestion, you can independently enable:
* Send Insights
* Send Detections
Insights payloads are significantly larger than detection payloads and are more likely to exceed default SIEM receiver size limits.
If you experience message fragmentation, truncation, or line-breaking issues:
* Consider sending detections only to your SIEM endpoint, or
* Configure separate webhook endpoints for insights and detections so each can be tuned independently.
#### Understanding Payload Size
Because multiple detections from a single workflow run are bundled into one webhook request, payload sizes will vary. A single payload may contain anywhere from 1 to many detection objects in the `data` array.
#### HTTP JSON Receiver
Configure your SIEM to accept webhooks via an HTTP/HTTPS endpoint that can receive JSON `POST` requests. Ensure your receiver is configured to read the **full HTTP request body** as a single JSON message, rather than splitting on newlines or fixed byte boundaries.
#### Line Breaking
{% hint style="danger" %}
**Important:** Do not configure line-breaking or message-splitting on the raw HTTP body. Each HTTP POST is one complete, self-contained JSON document. If your SIEM splits on newlines, the pretty-printed JSON will be broken across multiple events.
{% endhint %}
Configure your HTTP input to treat each request as a **single event**.
#### Event Flattening
If your SIEM requires **one event per detection** (rather than one event per workflow run), use your SIEM's JSON parsing or transformation pipeline to iterate over the `data` array and create individual events.
When flattening, carry forward the following parent fields into each individual event to preserve context:
* `id` (parent alert group ID)
* `customer`
* `owner`
* `repo`
* `repository`
* `run_id`
**Example: Flattening logic (pseudocode)**
```
for each detection in payload.data:
event = detection
event.alert_group_id = payload.id
event.customer = payload.customer
event.owner = payload.owner
event.repo = payload.repo
event.repository = payload.repository
event.run_id = payload.run_id
emit(event)
```
---
# Agent Instructions: 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:
```
GET https://docs.stepsecurity.io/administration/admin-console/integrations/webhook-integration.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.