SOP Connectivity & Event Fan-In

This document describes how external events trigger SOP runs.

Quick Paths

• MQTT Integration
• Webhook Integration
• Cron Integration
• Security Defaults
• Troubleshooting

1. Overview

ZeroClaw routes MQTT/webhook/cron/peripheral events through a unified SOP dispatcher (dispatch_sop_event).

Key behaviors:

• Consistent trigger matching: one matcher path for all event sources.
• Run-start audit: started runs are persisted via SopAuditLogger.
• Headless safety: in non-agent-loop contexts, ExecuteStep actions are logged as pending (not silently executed).

2. MQTT Integration

2.1 Configuration

Configure broker access with zeroclaw config set channels.mqtt.<field> <value> — the keys land under [channels.mqtt] in the stored config. See the Config reference for all fields. The use_tls flag must match the scheme of broker_url (mqtts:// ⇒ true, mqtt:// ⇒ false).

2.2 Trigger Definition

In SOP.toml:

[[triggers]]
type = "mqtt"
topic = "sensors/alert"
condition = "$.severity >= 2"

MQTT payload is forwarded into SOP event payload (event.payload), then shown in step context.

3. Webhook Integration

3.1 Endpoints

• POST /sop/{*rest}: SOP-only endpoint. Returns 404 if no SOP matches. No LLM fallback.
• POST /webhook: chat endpoint. It attempts SOP dispatch first; if no match, falls back to normal LLM flow.

Path matching is exact against configured webhook trigger path.

Example:

• Trigger path in SOP: path = "/sop/deploy"
• Matching request: POST /sop/deploy

3.2 Authorization

When pairing is enabled (default), provide:

1. Authorization: Bearer <token> (from POST /pair)
2. Optional second layer: X-Webhook-Secret: <secret> when webhook secret is configured

3.3 Idempotency

Use:

X-Idempotency-Key: <unique-key>

Defaults:

• TTL: 300s
• Duplicate response: 200 OK with "status": "duplicate"

Idempotency keys are namespaced per endpoint (/webhook vs /sop/*).

3.4 Example Request

curl -X POST http://127.0.0.1:42617/sop/deploy \
  -H "Authorization: Bearer <token>" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"message":"deploy-service-a"}'

Typical response:

{
  "status": "accepted",
  "matched_sops": ["deploy-pipeline"],
  "source": "sop_webhook",
  "path": "/sop/deploy"
}

4. Cron Integration

The scheduler evaluates cached cron triggers using a window-based check.

• Window-based: events within (last_check, now] are not missed.
• At-most-once per expression per tick: if multiple fire points are in one poll window, dispatch happens once.

Trigger example:

[[triggers]]
type = "cron"
expression = "0 0 8 * * *"

Cron expressions support 5, 6, or 7 fields.

5. Security Defaults

6. Troubleshooting