V2-02: Freeze the webhook event and HMAC protocol

[DevFoundry-labs]

Outcome

Freeze a vendor-neutral, versioned webhook contract that authenticates exact request bytes and routes valid departures through the existing replay-safe case workflow.

Contract requirements

• Define POST /v1/intake/webhooks/{source_id}.
• Define required delivery, timestamp, key ID, content type, and sha256= signature headers.
• Sign a domain-separated message containing timestamp, delivery ID, and raw body.
• Require timing-safe comparison, timestamp skew, body limit, duplicate-header rejection, and JSON parsing only after authentication.
• Define current/previous key rotation using operator-owned file-backed secrets.
• Freeze the strict employee.departure.authorized event schema.
• Map event ID to the existing case idempotency key.
• Define exact replay, conflicting reuse, concurrent delivery, and safe audit behavior.
• Publish golden signing vectors and a threat-case-to-test matrix.

Acceptance criteria

• The protocol is implementable without FastAPI-specific domain dependencies.
• Unknown source/key and invalid signature share generic, non-enumerating errors.
• Replays cannot create a second case or external action.
• External events cannot inject approvals, roles, controls, waivers, or organization identity.
• No secret, signature, raw body, or sensitive header is stored in audit/log output.
• Compatibility and versioning rules are explicit.

Planning source

.dev/v2/WEBHOOK_SPEC.md.

Dependencies

Blocked by #8. Contract changes discovered during M0 must be resolved before implementation issues open.