SOP Webhooks

SOP (Sophosic Operating Protocol) runs can optionally POST a JSON payload to a configured URL when they finish. Each request is signed with an HMAC header for security verification.

Overview

When an SOP run completes, the system can automatically notify your application via a webhook POST request. This enables you to:

Track SOP execution completion
Trigger downstream workflows
Log execution results
Update external systems with SOP outputs

HMAC Signature

Each webhook request includes a signature header for verification:


X-SOP-Signature: sha256=<hex_digest>

The signature ensures that the webhook request originates from the Sophosic Platform and hasn’t been tampered with.

Payload Structure

The webhook POST request includes a JSON payload with the following structure:


{
  "id": "<run id>",
  "sop_id": "<sop id>",
  "status": "completed",
  "output": {}
}

Payload Fields

id - Unique identifier for the SOP run
sop_id - Identifier of the SOP that was executed
status - Execution status (e.g., "completed", "failed")
output - JSON object containing the SOP execution results

Security Best Practices

Verify HMAC Signature - Always validate the X-SOP-Signature header
Use HTTPS - Configure webhook URLs with HTTPS only
Validate Payload - Check that the payload structure matches expectations
Rate Limiting - Implement rate limiting on your webhook endpoint
Idempotency - Handle duplicate webhook deliveries gracefully using the run id

Configuration

Configure webhooks through the SOP settings when creating or updating an SOP. Provide:

Webhook URL - HTTPS endpoint to receive POST requests
Secret - Shared secret for HMAC signature verification (automatically generated)

Troubleshooting

Webhook Not Received

Check that the webhook URL is accessible from the internet
Verify firewall rules allow incoming connections
Review webhook endpoint logs for errors

Signature Verification Failures

Ensure you’re using the correct shared secret
Verify HMAC algorithm matches (SHA256)
Check timestamp tolerance for replay attack prevention

Trigger Authentication - Learn how to trigger SOPs from external systems