Webhook and evidence connectors

Normalize authenticated webhook deliveries into incidents, and collect remote evidence through the hardened HTTP JSON plugin.

PHASE 1 · PRE-1.0PYTHON 3.11+EDIT ON GITHUB ↗

Generic webhook normalization

Lumis SDK does not embed a web server. Your application receives the request however it likes, then passes the exact body bytes and headers to normalize_webhook along with explicit security configuration and a replay guard:

python

from lumis_sdk.adapters.incidents import (
    InMemoryReplayGuard,
    WebhookConfig,
    normalize_webhook,
)

incident = normalize_webhook(
    body,
    headers,
    WebhookConfig(
        source_tool="pipeline-events",
        secret_env="PIPELINE_WEBHOOK_SECRET",
    ),
    InMemoryReplayGuard(),
)

The adapter verifies an HMAC signature (sha256=<hex> over "<unix timestamp>.<body bytes>") in constant time, enforces clock-skew and payload limits, parses unique-key UTF-8 JSON with depth and node bounds, requires strict delivery IDs, and fails closed on replay claims. The in-memory guard suits local tools and tests; multi-process deployments must supply a durable atomic ReplayGuard.

HTTP JSON evidence plugin

The independently packaged lumis-sdk-http-json-evidence plugin implements EvidenceProvider without adding httpx to core:

yaml

spec:
  evidenceProviders:
    - provider: http-json
      url: https://evidence.example.test/v1/evidence
      allowedOrigins: [https://evidence.example.test]
      tokenEnv: LUMIS_EVIDENCE_TOKEN
      maxResponseBytes: 1000000
      timeoutSeconds: 5
      retries: 1

The connector requires HTTPS with an exact origin allowlist, never follows redirects, loads only the named token reference, sends minimized incident metadata rather than raw payloads, bounds response bytes before JSON parsing, and returns structured failures. EvidenceService still enforces kinds, item counts, character budgets, duplicate IDs, timeouts, and redaction on top.