Verify signed webhooks against raw bytes before parsing
The receiver parses JSON and reserializes it before checking the supplier signature. Harmless whitespace changes break valid signatures, while trusted routing fields are read before authenticity is established.
- Focused work estimate
- 3h 30m + prerequisites
- Priority in the scenario
- High
- Engineering practice
- Webhook authentication · Byte-level contracts · Constant-time comparison
Estimated field mix
- Security60%
- Integrations40%
Field percentages are editorial estimates of the ticket's engineering focus. They total 100%; they are not measured time, proficiency scores, or ownership evidence.
Review it, then add it to your workspace.
The board opens an editable draft; nothing is saved until you confirm it. Sign-in and workspace permissions apply, and Demo boards remain ephemeral.
Project context
A fictional supplier integration signs incoming webhooks and uses an outbound API credential. Operators currently replace environment values by hand. Build with a deterministic secret-store adapter and fabricated keys only; no live provider account or production credential is part of the exercise.
Setup prerequisites
- Cryptographic hash APIs
- HTTP webhook handling
- Access control
Preceding work
Complete these dependencies, or supply their agreed outputs before taking this ticket.
Acceptance criteria
- Verify the exact bounded raw body using the fixture protocol's HMAC signature format.
- Use constant-time comparison for equal-length signature bytes and reject malformed encodings.
- Parse trusted fields only after successful verification and enforce the protocol's timestamp tolerance.
Implementation constraints
- The fixture protocol signs timestamp plus raw body with HMAC-SHA-256; define the byte separator explicitly.
Verification to include
- Accept a correctly signed body including deliberate whitespace.
- Reject one-byte changes, invalid signature length, and timestamps outside the declared tolerance.
Deliverables
- Raw-body webhook verification and protocol fixtures
Rollout and recovery
Run signature checks on a fixture receiver first; fail closed when verification material is unavailable.
Value of the work
For the engineer: Practice credential lifecycle design, overlap windows, authenticated webhooks, and failure recovery without handling real secrets.
For the team: Review whether an engineer can make rotation auditable and fail closed while preserving availability and replay safety.
Evidence boundaries
Outcome Evidence: Tests, patches, and runbooks are requested deliverables. They become Outcome Evidence only through a qualified Mission and immutable Evidence IDs.
Ownership Evidence: Independent adaptation must be observed under a declared verification policy and cite immutable Evidence IDs. Completing a planning ticket establishes no Ownership Evidence.