[feature] HMAC-SHA256 webhook signature verification (X-KeeperHub-Signature)

[B2JK-Industry]

Friction

KeeperHub workflow webhooks today authenticate the caller via Authorization: Bearer wfb_<token>. There's no documented mechanism for a workflow's destination service (when KH itself POSTs to e.g. our executor_callback URL on a future inbound flow) to verify the request actually came from KH and wasn't spoofed. Adapter authors building reverse-direction integrations (KH → SBO3L for status callbacks, audit-trail mirrors, IP-3-style capsule-bound result delivery) have to either:

1. Trust the source IP / TLS hostname (brittle; doesn't survive reverse proxies)
2. Reverse-engineer KH's signature scheme from raw HTTP captures (none documented today)

Proposed fix

Document + implement HMAC-SHA256 signature header on every KH-initiated webhook delivery, mirroring the well-trodden Stripe / GitHub / Slack pattern:

X-KeeperHub-Signature: sha256=<hex(hmac_sha256(secret, body))>
X-KeeperHub-Timestamp: 1714478400

The destination registers a shared secret per webhook config in the KH workflow UI. Replay protection via the timestamp + a documented N-second tolerance window (Stripe uses 5 min).

Reference

• Stripe: https://docs.stripe.com/webhooks#verify-official-libraries
• GitHub: https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
• Slack: https://api.slack.com/authentication/verifying-requests-from-slack

Context

Filed as part of SBO3L's KeeperHub Builder Feedback round 3 for ETHGlobal Open Agents 2026. Companion to #51 (Idempotency-Key on inbound) — together they define the bidirectional security contract.