WebHook Gateway Integration

The HLD WebHook Gateway is a lightweight, stateless relay that delivers agent completion events to registered HTTPS endpoints. Agents call the local gateway; the gateway fans out to every subscribed target with automatic retries and deterministic ordering.

Core Flow

Agent completes task
       │
       ▼
POST /api/v1/webhooks/fire  (local gateway, port 9090)
       │
       ├─► Telegram Gateway  (user notification)
       ├─► CI/CD Webhook     (deployment trigger)
       ├─► Audit Logger      (immutable trail)
       └─► Custom Endpoint   (downstream service)

Agent Usage

Every Fleet agent has the webhook tool available. No SDK import — the runtime injects it at spawn.

# Agent code (any language, subprocess or HTTP)
import httpx, json, os

GW = os.getenv("WEBHOOK_GATEWAY", "http://127.0.0.1:9090")

def notify_complete(task_id: str, result: dict, targets: list[str] = None):
    payload = {
        "event": "task.completed",
        "agent": os.getenv("AGENT_ID"),
        "task_id": task_id,
        "result": result,
        "ts": int(time.time()),
    }
    params = {"targets": targets} if targets else {}
    httpx.post(f"{GW}/api/v1/webhooks/fire", json=payload, params=params, timeout=5.0)

Bash (cybot-run / terminal agents)

curl -s -X POST http://127.0.0.1:9090/api/v1/webhooks/fire \
  -H "Content-Type: application/json" \
  -d '{"event":"task.completed","agent":"CY","task_id":"t-123","result":{"status":"ok"},"ts":1723555200}'

Gateway Configuration

File: /opt/hld-gateway/webhook_gateway.yaml

targets:
  telegram:
    url: "https://telegram-gateway.highlimitdesigns.com/internal/webhook"
    headers:
      X-API-Key: ${TELEGRAM_GATEWAY_KEY}
    retry: 3
    backoff_ms: 500

  audit:
    url: "https://audit.highlimitdesigns.com/ingest"
    headers:
      Authorization: Bearer ${AUDIT_TOKEN}
    retry: 5
    backoff_ms: 1000

  # Addcustom: name, url, headers, retry, backoff_ms

Delivery Guarantees

At-least-once — transient failures retry with exponential backoff
Ordered per target — sequence numbers prevent reordering under retry
Idempotency key — X-Idempotency-Key: <agent>-<task_id>-<event> enables safe deduplication
Timeout — 5s per target; slow targets never block others

Payload Schema

{
  "event": "task.completed | task.failed | agent.spawned | agent.terminated",
  "agent": "CY | AXON | CIPHER | ...",
  "task_id": "string",
  "result": { "...": "arbitrary JSON" },
  "ts": 1723555200,
  "idempotency_key": "CY-t-123-task.completed"
}

Local Development

# Run gateway in foreground (hot reload config)
./webhook_gateway --config webhook_gateway.yaml --dev

# Test fire
curl -X POST localhost:9090/api/v1/webhooks/fire -d '{"event":"test","agent":"DEV","task_id":"x","result":{},"ts":0}'

Monitoring

Health: GET /health → 200 + target connectivity matrix
Metrics: Prometheus /metrics — webhook_delivered_total{target,status}, webhook_latency_seconds{target}

Security

Gateway only accepts requests from 127.0.0.1 (agent runtime) — no external ingress
Outbound X-API-Key / Authorization headers sourced from sealed env, never logged
Payloads never contain secrets — agents must sanitize result before firing

Authentication Overview

Overview

Webhook Gateway