Review webhook signature verification

Review exercise · TypeScript

Review brief

Beginner20 min

A billing integration is adding HMAC verification before webhook events reach application handlers. The HTTP adapter supplies lowercase header names and the exact request-body bytes, and this verifier owns authentication and timestamp freshness.

Behavioral contract

The provider sends x-webhook-timestamp as a finite integer Unix timestamp in seconds and x-webhook-signature as 64 lowercase hexadecimal characters.
The shared secret is nonempty and nowSeconds is a finite integer supplied by the trusted server clock.
The expected signature is HMAC-SHA256 using the shared secret over the ASCII timestamp, one period byte, and the exact raw request-body bytes in that order.
A delivery is fresh only when its timestamp is no more than 300 seconds old and no more than 300 seconds in the future relative to nowSeconds.
Malformed or missing headers, invalid JSON, stale deliveries, future deliveries outside the window, and signature mismatches must return false rather than throw.
Digest comparison must not reveal a matching prefix through data-dependent timing.
Duplicate-event suppression after successful authentication is handled downstream and is outside this review.

Review instructions

1Review only the changed code against the behavioral contract in the brief.
2Anchor each finding to the narrowest useful changed line and explain the authentication impact.
3Recommend a direction rather than writing replacement code.
4Prioritize no more than four findings.

Learning objectives

• Preserve the exact byte representation covered by a signature
• Validate timestamp freshness at both boundaries
• Recognize comparison and test choices that weaken verification

src/webhook-signature.tsTypeScript

@@ -0,0 +1,42 @@

1+import { createHmac } from "node:crypto";

3+const MAX_CLOCK_SKEW_SECONDS = 300;

5+export interface WebhookHeaders {

6+ readonly "x-webhook-signature"?: string;

7+ readonly "x-webhook-timestamp"?: string;

8+}

10+export function verifyWebhookSignature(

11+ rawBody: Uint8Array,

12+ headers: WebhookHeaders,

13+ secret: string,

14+ nowSeconds: number,

15+): boolean {

16+ const suppliedSignature = headers["x-webhook-signature"];

17+ const timestampHeader = headers["x-webhook-timestamp"];

18+

19+ if (suppliedSignature === undefined || timestampHeader === undefined) {

20+ return false;

21+ }

22+

23+ const timestamp = Number(timestampHeader);

24+ const ageSeconds = nowSeconds - timestamp;

25+ if (ageSeconds > MAX_CLOCK_SKEW_SECONDS) {

26+ return false;

27+ }

28+

29+ let normalizedBody: string;

30+ try {

31+ const decoded = new TextDecoder().decode(rawBody);

32+ normalizedBody = JSON.stringify(JSON.parse(decoded));

33+ } catch {

34+ return false;

35+ }

36+

37+ const expectedSignature = createHmac("sha256", secret)

38+ .update(`${timestampHeader}.${normalizedBody}`)

39+ .digest("hex");

40+

41+ return expectedSignature === suppliedSignature;

42+}

Reference solution

The findings below are ordered by priority.

Findings

1. Verification authenticates a rewritten payload instead of the received bytes

Location: src/webhook-signature.ts:29-39

The verifier parses the JSON and serializes it again before computing the HMAC. Whitespace, key ordering, and number spelling can all change during that round trip, so a valid provider signature over the original bytes can be rejected. More importantly, verification no longer proves the exact message representation the HTTP server received.

Parse only after authentication. Build the HMAC input from the timestamp bytes, the period separator, and rawBody without decoding or normalizing the body.

2. Malformed and sufficiently future-dated timestamps pass the freshness gate

Location: src/webhook-signature.ts:22-26

Number can produce NaN, and the one-sided age comparison is false for both NaN and every future timestamp. A correctly signed request can therefore use a malformed timestamp or a timestamp arbitrarily far ahead and still reach signature comparison, defeating the bounded freshness contract.

Require the timestamp text to represent a finite integer, then reject when the signed timestamp differs from nowSeconds by more than 300 seconds in either direction.

3. Comparing digest strings leaks data-dependent timing

Location: src/webhook-signature.ts:36-41

Ordinary string equality is not a constant-time authentication primitive. Its work can depend on where two strings differ, which creates an avoidable timing side channel at a remotely reachable verification boundary. The code also never validates the supplied digest's exact hexadecimal shape before comparison.

Validate and decode the 64-character lowercase hexadecimal signature, check the buffer length, and compare equal-length digest bytes with a constant-time primitive.

4. The test covers only a normalized happy-path body

Location: src/webhook-signature.test.ts:6-29

The test signs the same compact JSON.stringify representation that the verifier recreates and uses a timestamp exactly equal to now. It cannot detect raw-body normalization, malformed timestamps, either freshness boundary, missing headers, or mismatched signatures.

Add focused cases for byte-distinct but semantically equivalent JSON, invalid header shapes, old and future boundary values, and a changed digest.

Reasonable non-findings

Returning false for invalid JSON is consistent with the contract.
HMAC-SHA256 and lowercase hexadecimal output match the provider protocol.
The verifier may rely on the adapter to supply exact body bytes and lowercase header names.