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

{
  "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

{
  "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.

---

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

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.

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)