Before shipping it, separate protocol facts, product promises, and operating cost. Mixing those layers produces confident but incorrect decisions. Parsing and reserializing JSON changes whitespace and key order. Verify bounded raw bytes before the body parser.
An API contract includes units, defaults, idempotency, error classes, and version windows—not only field types. Clients distinguish retryable, user-action, and permanent outcomes to avoid duplicate side effects.
The parts that make the design practical
This capability crosses clients, networks, and servers, so a local optimization can create a system failure. Decisions must constrain both endpoints, persisted truth, and operating budgets together.
- Sign version.timestamp.eventId.body, enforce a window, persist eventId dedupe, accept current and previous keys, and compare in constant time.
- Bound every input by size, count, and time, returning a stable actionable error code when a budget is exceeded.
- Retries need an idempotency key, backoff, and deadline; after the deadline create a new task instead of reviving old callbacks.
The delivery standard for Webhook Signature Verification with Raw Bodies and Replay Records is a usable normal path, convergent failures, bounded resources, and a state users can understand. The result is a production capability that can be explained, degraded safely, and rolled back—not a demo that works once.
Keep false assumptions out of production
Prioritize faults that silently preserve false facts: the interface looks recovered while a queue, permission, or counter has diverged. The defect often appears only on the next action.
- A timestamp without eventId allows replay inside the window, while logging signatures and bodies leaks credentials and event content.
- Fixing only the UI leaves queues, locks, or expired credentials for the next operation to inherit and fail again.
- Without backpressure or quota, a slow consumer raises memory, queue depth, and tail latency until unrelated users are affected.
What the release gate should inspect
A release gate combines deterministic regression, randomized timing, and real browser pairs. Preserve the seed and state trace from every failure as a permanent replay case.
- Cover whitespace, gzip, duplicate event, expiry, future clock, dual keys, and one-bit mutation; valid retries dedupe and forgeries fail consistently.
- Disconnect, change networks, and recover mid-operation; reconcile endpoint state, persistence, and resource counts.
- Before release, record success rate, p50/p95/p99 latency, error classes, and resource high-water marks with explicit rollback thresholds.
The result must be correct, recoverable, and explainable. If any part depends on refreshing the page or an engineer guessing, the protocol loop remains incomplete.