Create action

This guide covers how to define and trigger automated actions in S4E through the REST API. Actions are the building blocks of automated security response workflows.

What Are Actions?

An action is a discrete, automated step that S4E can execute in response to a security event. Actions serve as the foundation for playbooks and can also be triggered independently. Typical use cases include:

Sending a notification to a Slack channel when a critical vulnerability is found.
Triggering a remediation script on the affected host.
Forwarding event data to a third-party system via webhook.
Executing a predefined remediation routine (e.g., rotating a certificate, blocking an IP).

Endpoint

POST https://api.s4e.io/api/actions

Required Headers

Header	Value	Description
Authorization	`Bearer <token>`	Your API authentication token.
Content-Type	`application/json`	Request body format.

Request Payload

Field	Type	Required	Description
name	string	Yes	Human-readable name for the action.
type	string	Yes	Action type (see table below).
target	string	Yes	Destination identifier - depends on the action type.
parameters	object	No	Type-specific configuration (see per-type sections).
conditions	object	No	Conditions that must be met before the action fires.

Action Types

Type	Description	Target Value
notification	Send an alert via email, Slack, Microsoft Teams, or PagerDuty.	Channel URL or email address.
remediation	Execute a predefined remediation task on the asset.	Remediation template ID.
webhook	Send an HTTP POST to an external URL with event data.	Fully qualified webhook URL.
script	Run a custom script stored in the S4E script library.	Script ID from the library.

Conditions Object

Conditions control when an action should fire. All fields are optional; omitting conditions means the action fires unconditionally when invoked.

Field	Type	Description
severity_min	string	Minimum severity to trigger: `info`, `low`, `medium`, `high`, `critical`.
asset_tags	string[]	Only fire if the asset has all listed tags.
finding_status	string	Only fire for findings with this status (e.g., `open`).
schedule	string	Cron expression for time-based conditions (e.g., `0 9 * * 1-5`).

Note

Conditions are evaluated with AND logic. Every specified condition must be satisfied for the action to execute.

Response Format

A successful request returns 201 Created:

{
  "id": "act-11223344-5566-7788-99aa-bbccddeeff00",
  "name": "Notify Slack on Critical Finding",
  "type": "notification",
  "target": "https://hooks.slack.com/services/T00/B00/xxxxx",
  "parameters": {
    "channel": "#security-alerts",
    "mention": "@oncall"
  },
  "conditions": {
    "severity_min": "critical",
    "finding_status": "open"
  },
  "created_at": "2026-04-28T09:00:00Z",
  "enabled": true
}

Field	Type	Description
id	string	Unique action identifier.
name	string	Action name as provided.
type	string	Action type.
target	string	Target destination.
parameters	object	Type-specific configuration.
conditions	object	Trigger conditions.
created_at	string	ISO 8601 creation timestamp.
enabled	boolean	Whether the action is active.

Type-Specific Parameter Reference

notification

Parameter	Type	Description
channel	string	Target channel or recipient within the platform.
mention	string	User or group to mention/page in the notification.
template	string	Optional message template with variable placeholders.

remediation

Parameter	Type	Description
auto_apply	boolean	Apply the fix automatically (default `false`).
dry_run	boolean	Simulate without making changes (default `true`).
rollback_on_failure	boolean	Revert changes if the remediation fails.

webhook

Parameter	Type	Description
headers	object	Custom HTTP headers to include in the request.
secret	string	HMAC secret for request signing.
retry_count	integer	Number of retry attempts on failure (max 5).

script

Parameter	Type	Description
args	string[]	Command-line arguments passed to the script.
timeout	integer	Maximum execution time in seconds.
env	object	Environment variables injected at runtime.

Triggering an Action Manually

You can execute any action on demand, regardless of its conditions:

POST https://api.s4e.io/api/actions/{action_id}/trigger

The request body is optional. If provided, it can include context data:

{
  "asset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "finding_id": "f-00112233-4455-6677-8899-aabbccddeeff"
}

The response returns 200 OK with an execution summary:

{
  "execution_id": "exec-aabb1122-3344-5566-7788-99aabbccddee",
  "action_id": "act-11223344-5566-7788-99aa-bbccddeeff00",
  "status": "triggered",
  "triggered_at": "2026-04-28T09:05:00Z"
}

Warning

Manual triggers bypass all conditions defined on the action. Use this capability carefully, especially for remediation and script actions that modify infrastructure.

Error Handling

HTTP Code	Meaning	Typical Cause
400	Bad Request	Invalid payload or unsupported action type.
401	Unauthorized	Missing or expired Bearer token.
403	Forbidden	Insufficient permissions.
409	Conflict	An action with this name already exists.
422	Unprocessable Entity	Target validation failed (e.g., unreachable webhook URL).

Example: Create a Slack Notification Action

curl -X POST https://api.s4e.io/api/actions \
  -H "Authorization: Bearer $S4E_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Notify Slack on Critical Finding",
    "type": "notification",
    "target": "https://hooks.slack.com/services/T00/B00/xxxxx",
    "parameters": {
      "channel": "#security-alerts",
      "mention": "@oncall"
    },
    "conditions": {
      "severity_min": "critical",
      "finding_status": "open"
    }
  }'

Tip

After creating an action, test it immediately using the manual trigger endpoint to verify that the target is reachable and the parameters are correct.