Webhooks & SOAR Integration

SoCMate provides notification events and API endpoints that enable integration with SOAR platforms (Palo Alto XSOAR, Splunk SOAR, Microsoft Sentinel Playbooks), ticketing systems, and custom automation workflows.

Integration Architecture

SoCMate                          External Systems
┌──────────────────────┐         ┌───────────────────────┐
│  Investigation       │         │  SOAR Platform        │
│  Completes           │────────>│  (XSOAR, Splunk SOAR) │
│                      │ notify  │                       │
│  New Incident        │────────>│  Ticketing System     │
│  Synced              │ notify  │  (ServiceNow, Jira)   │
│                      │         │                       │
│  Schedule Run        │────────>│  Custom Webhook       │
│  Completes/Fails     │ notify  │  Consumer             │
└──────────────────────┘         └───────────┬───────────┘
                                             │
                                     API calls back
                                             │
                                             ▼
                                 ┌───────────────────────┐
                                 │  SoCMate API          │
                                 │  (X-API-Key auth)     │
                                 └───────────────────────┘

Event Types

SoCMate generates notification events for the following actions:

Event	Trigger	Typical Use
`incident-alert`	New Medium/High/Critical incident synced from Sentinel	Create a ticket, trigger a SOAR playbook
`investigation-completed`	Scheduled investigation finishes	Review results, update case management
`investigation-failed`	Scheduled investigation encounters an error	Alert on-call analyst, trigger retry logic
`schedule-disabled`	Schedule auto-disabled after 5 consecutive failures	Notify admin for review

SOAR Integration Pattern

The recommended integration pattern uses SoCMate’s API for pull-based integration:

Set up polling or event triggers

Configure your SOAR platform to periodically poll SoCMate for new incidents or investigation results, or use SoCMate’s notification system to receive events.

Create an API key

Create a SoCMate API key with appropriate scopes for your integration:

curl -X POST https://api.socmate.yourcompany.com/api/admin/api-keys \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "XSOAR Integration",
    "scopes": ["investigations:read", "investigations:write", "incidents:read"],
    "expires_in_days": 365
  }'

Poll for incidents

Your SOAR platform polls SoCMate for new high-severity incidents:

curl -X GET "https://api.socmate.yourcompany.com/api/v1/incidents?severity=high&status=new&timespan=PT1H" \
  -H "X-API-Key: sk_live_..."

Trigger investigations

When your SOAR playbook identifies an incident that needs investigation, trigger a SoCMate investigation:

curl -X POST https://api.socmate.yourcompany.com/api/v1/investigations/start \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Investigate Sentinel incident #12345 — multiple failed MFA attempts",
    "persona": "soc_analyst",
    "provider": "sentinel"
  }'

Retrieve results

Poll for investigation completion and retrieve the report:

# Check status
curl -X GET https://api.socmate.yourcompany.com/api/v1/sessions/sess_abc123 \
  -H "X-API-Key: sk_live_..."

# When status is "completed", extract the report

Notification Payload Format

Events delivered through SoCMate’s notification system follow this structure:

Incident Alert

{
  "event_type": "incident-alert",
  "timestamp": "2026-03-27T10:30:00Z",
  "data": {
    "incident_number": 12345,
    "title": "Multiple failed sign-in attempts detected",
    "severity": "high",
    "status": "new",
    "provider": "sentinel",
    "url": "https://socmate.yourcompany.com/incidents/12345"
  }
}

Investigation Completed

{
  "event_type": "investigation-completed",
  "timestamp": "2026-03-27T10:35:00Z",
  "data": {
    "session_id": "sess_abc123",
    "schedule_id": "sched_xyz789",
    "schedule_name": "Daily failed sign-in check",
    "title": "Failed sign-in investigation",
    "risk_score": 7.5,
    "entity_count": 5,
    "finding_count": 3,
    "url": "https://socmate.yourcompany.com/investigations/sess_abc123"
  }
}

Investigation Failed

{
  "event_type": "investigation-failed",
  "timestamp": "2026-03-27T10:35:00Z",
  "data": {
    "session_id": "sess_abc123",
    "schedule_id": "sched_xyz789",
    "schedule_name": "Daily failed sign-in check",
    "error": "Sentinel query execution timed out after 120 seconds",
    "consecutive_failures": 2,
    "url": "https://socmate.yourcompany.com/schedules/sched_xyz789"
  }
}

Example: XSOAR Playbook

A typical XSOAR integration flow:

XSOAR Playbook: SoCMate Investigation
┌─────────────────────────────────┐
│ 1. Trigger: New Sentinel Alert  │
│                                 │
│ 2. Extract IOCs from alert      │
│                                 │
│ 3. Call SoCMate API:            │
│    POST /investigations/start   │
│    with extracted IOCs          │
│                                 │
│ 4. Wait / Poll for completion   │
│    GET /sessions/{session_id}   │
│                                 │
│ 5. Parse investigation report   │
│    - Extract risk score         │
│    - Extract recommendations    │
│                                 │
│ 6. Decision:                    │
│    risk_score >= 7 → Escalate   │
│    risk_score < 7  → Log       │
│                                 │
│ 7. Update ticket with report    │
└─────────────────────────────────┘

Example: Sentinel Playbook (Logic App)

SoCMate can be called from a Microsoft Sentinel Playbook (Azure Logic App) when an incident is created:

{
  "type": "Http",
  "inputs": {
    "method": "POST",
    "uri": "https://api.socmate.yourcompany.com/api/v1/investigations/start",
    "headers": {
      "X-API-Key": "@{parameters('SoCMateApiKey')}",
      "Content-Type": "application/json"
    },
    "body": {
      "query": "Investigate: @{triggerBody()?['properties']?['title']}",
      "persona": "soc_analyst",
      "provider": "sentinel"
    }
  }
}

"""Poll SoCMate for new high-severity incidents and create Jira tickets."""
import httpx
import time

SOCMATE_API = "https://api.socmate.yourcompany.com"
API_KEY = "sk_live_..."

client = httpx.Client(headers={"X-API-Key": API_KEY})

# Get new high-severity incidents from the last hour
incidents = client.get(
    f"{SOCMATE_API}/api/v1/incidents",
    params={"severity": "high", "status": "new", "timespan": "PT1H"},
).json()

for incident in incidents.get("incidents", []):
    # Trigger an investigation
    session = client.post(
        f"{SOCMATE_API}/api/v1/investigations/start",
        json={
            "query": f"Investigate incident: {incident['title']}",
            "persona": "soc_analyst",
            "provider": "sentinel",
        },
    ).json()

    print(f"Started investigation {session['session_id']} for incident {incident['incident_number']}")

API Endpoints for Integration

Endpoint	Method	Description
`/api/v1/incidents`	GET	List synced Sentinel incidents
`/api/v1/incidents/{number}`	GET	Get incident details
`/api/v1/incidents/{number}/enrich`	POST	Trigger deterministic enrichment
`/api/v1/investigations/start`	POST	Start an investigation
`/api/v1/sessions/{id}`	GET	Get investigation results
`/api/v1/search`	GET	Search past investigations
`/api/v1/graph/entity/{value}`	GET	Query knowledge graph

Best Practices

Use dedicated API keys — Create a separate API key for each integration with minimum required scopes
Handle rate limits — Implement retry logic with exponential backoff for 429 responses
Poll efficiently — Use time-based filters (timespan) to avoid re-processing old data
Check investigation status — Investigations take 30-120 seconds; poll the session endpoint rather than blocking
Log API key usage — Monitor last_used_at in the admin panel to track integration activity

​Integration Architecture

​Event Types

​SOAR Integration Pattern

​Notification Payload Format

​Incident Alert

​Investigation Completed

​Investigation Failed

​Example: XSOAR Playbook

​Example: Sentinel Playbook (Logic App)

​API Endpoints for Integration

​Best Practices