Webhooks are input adapters

Webhook processing flow

receive webhook
  → verify signature and timestamp
  → reject duplicate event_id
  → validate schema
  → load workflow and current state
  → map event to ControlManager context
  → execute opaque control steps
  → accept validated state commits
  → persist result and audit record
  → acknowledge delivery

Design for delivery semantics

• Verify an HMAC or provider signature before parsing trusted fields.
• Use `event_id` as an idempotency key because providers retry deliveries.
• Persist receipt before long-running work and return a fast acknowledgement.
• Process asynchronously when node execution can exceed the sender’s timeout.
• Keep the raw event, normalized envelope, execution trace, and resulting state transition correlated by trace ID.

Adapter versus runtime API

Provider-specific webhook routes belong at the integration boundary. They should not contain routing or state-transition logic.

After authentication and normalization, the adapter should call ControlManager (or POST /api/v1/control/runs) with the intent, persisted current state, relevant history, state data, and event metadata.