Backend | Toolbox Guides & Articles

HMAC-SHA256 Webhook Signature Verification: RFC 2104 Internals and Provider Formats

Sun, 06 Sep 2026 00:00:00 +0000

Interactive Workbench LIVE

HMAC-SHA256 Webhook Signature Verification: RFC 2104 Internals and Provider Formats

Open Fullscreen ↗

Initializing Workbench...

100% Client-Side RAM Sandbox

🔒 Private Execution: Computations run in local browser memory. Zero server uploads. Zero server uploads.

Launch Fullscreen →

Free In-Browser Tool TOOLBOX UTILITY

HMAC Signature Generator & Verifier

Paste a payload and secret, choose SHA-256, SHA-384, SHA-512, or SHA-1, and compare the computed digest against the signature you received.

Open HMAC Generator & Verifier →

The Problem HMAC Solves

You receive an HTTP POST claiming to be a payment confirmation. The body says an order was paid. Acting on it moves inventory and money. Two questions must be answered before your code touches the database:

Authenticity — did this come from the provider, or from anyone who found the endpoint URL?
Integrity — is the body byte-for-byte what the provider sent, or was an amount edited in transit?

A Keyed-Hash Message Authentication Code answers both. The provider holds a secret, you hold the same secret, and the provider attaches a tag that only a holder of that secret could have produced over that exact payload.

What you get from this guide: the construction, the specific attack that motivates it, working verification code for three major providers, and the four mistakes that cause almost every “signature invalid” incident.

The RFC 2104 Construction

HMAC(K, m) = H( (K' XOR opad) || H( (K' XOR ipad) || m ) )

Term	Definition
`H`	Underlying hash function (SHA-256, SHA-512, SHA-1)
`B`	Hash block size in bytes — 64 for SHA-1/SHA-224/SHA-256, 128 for SHA-384/SHA-512
`K'`	The key, normalised to exactly `B` bytes
`ipad`	Byte `0x36` repeated `B` times (inner pad)
`opad`	Byte `0x5C` repeated `B` times (outer pad)
`

Key normalisation matters: a key shorter than B is right-padded with zero bytes; a key longer than B is first hashed with H, and that digest becomes the key. This means a 200-character secret and its SHA-256 digest produce identical HMACs — a detail that occasionally explains why two “different” secrets validate the same payload.

Why not `H(secret || message)`?

Because SHA-1 and the SHA-2 family are Merkle–Damgård constructions that expose their internal state as the output digest. Given H(secret || message) and the length of secret || message, an attacker can resume the hash from that state and compute a valid digest for secret || message || padding || evil — without ever learning the secret. That is a length-extension attack, and it turns a naive “signature” into a forgery oracle.

Block sizes and digest lengths

Hash function	Block size `B`	Digest	Hex characters
MD5	64 bytes	128 bits	32
SHA-1	64 bytes	160 bits	40
SHA-256	64 bytes	256 bits	64
SHA-384	128 bytes	384 bits	96
SHA-512	128 bytes	512 bits	128

The two pads are the whole trick: ipad and opad differ in exactly half their bits, so the inner and outer passes behave like two independent keyed functions.

The double-pad nesting in HMAC means the attacker only ever sees the output of the outer hash, whose input they cannot control or extend. This is why RFC 2104 (1997) and FIPS PUB 198-1 (2008) both standardise the nested form, and why crypto.createHmac exists in every standard library.

Provider Formats Compared

Provider	Header	Encoding	Signed data	Secret
Stripe	`Stripe-Signature`	hex, inside `t=…,v1=…`	`"{timestamp}.{raw_body}"`	endpoint secret (`whsec_…`)
GitHub	`X-Hub-Signature-256`	hex, prefixed `sha256=`	raw body	webhook secret
Shopify	`X-Shopify-Hmac-SHA256`	Base64	raw body	app client secret

All three use HMAC-SHA256 and all three require the unmodified raw body.

Stripe

The header carries a timestamp and one or more scheme-prefixed signatures:

Stripe-Signature: t=1492774577,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Verification, per Stripe’s manual procedure: split the header on , then =, build signed_payload as the timestamp, a literal ., and the raw JSON body, compute HMAC-SHA256 with the endpoint secret, compare in constant time, and reject if the timestamp is outside your tolerance. Stripe’s official libraries default to a five-minute tolerance, and Stripe advises ignoring any scheme that is not v1 to prevent downgrade attacks. During a secret roll, an endpoint can have two active secrets and the header then carries one v1 signature per secret — so compare against all v1 values, not just the first.

import crypto from "node:crypto";

export function verifyStripe(rawBody, header, secret, toleranceSec = 300) {
 const parts = Object.fromEntries(
 header.split(",").map((kv) => kv.split("=").map((s) => s.trim()))
 );
 const timestamp = Number(parts.t);
 if (!timestamp) return false;

 // Freshness: a valid signature is not a fresh one.
 if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSec) return false;

 const expected = crypto
 .createHmac("sha256", secret)
 .update(`${timestamp}.${rawBody}`, "utf8")
 .digest("hex");

 const received = header
 .split(",")
 .filter((kv) => kv.trim().startsWith("v1="))
 .map((kv) => kv.trim().slice(3));

 return received.some((sig) => timingSafeEqualHex(expected, sig));
}

function timingSafeEqualHex(a, b) {
 const ab = Buffer.from(a, "hex");
 const bb = Buffer.from(b, "hex");
 return ab.length === bb.length && crypto.timingSafeEqual(ab, bb);
}

GitHub

export function verifyGithub(rawBody, header, secret) {
 const expected =
 "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
 const a = Buffer.from(expected);
 const b = Buffer.from(header ?? "");
 return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Shopify

export function verifyShopify(rawBody, header, clientSecret) {
 const expected = crypto
 .createHmac("sha256", clientSecret)
 .update(rawBody, "utf8")
 .digest("base64");
 const a = Buffer.from(expected, "base64");
 const b = Buffer.from(header ?? "", "base64");
 return a.length === b.length && crypto.timingSafeEqual(a, b);
}

The Four Failure Modes

1. The body was parsed before you hashed it

The most common cause by a wide margin. express.json(), Django’s request handling, and Next.js route defaults may hand you a re-serialised object. Re-encoding {"a":1.0} as {"a":1}, reordering keys, or normalising Unicode escapes all change the byte string and therefore the digest. Stripe states the requirement plainly: the raw body must be the string it sent, in UTF-8, unchanged.

// Order matters. Mount the raw-body webhook route BEFORE the JSON parser.
app.post("/webhooks/stripe", express.raw({ type: "application/json" }), handler);
app.use(express.json());

2. Non-constant-time comparison

expected === received returns as soon as it hits a differing byte. That timing difference is measurable across enough requests and leaks the expected digest byte by byte. Use crypto.timingSafeEqual, hmac.compare_digest (Python), or hash_equals (PHP). Compare decoded bytes of equal length — timingSafeEqual throws on length mismatch, so check length first.

3. No replay protection

A valid signature says “this was authentic when created”. It says nothing about when. Sign a timestamp (Stripe’s model) and enforce a tolerance, or store processed delivery IDs and drop repeats. Stripe also warns against setting the tolerance to 0, which disables the recency check entirely.

4. Signature comparison as the only gate

Also validate that the event type is one you handle, return 2xx quickly and process asynchronously, and treat delivery as at-least-once — providers retry, and duplicate events are normal. Stripe explicitly does not guarantee ordering, so deduplicate on event ID rather than trusting timestamps.

Hex, Base64, or Base64url — Match the Provider Exactly

One 32-byte HMAC-SHA256 tag has several textual forms, and mismatched encoding is the second most common cause of failed verification after raw-body mistakes.

Encoding	Length for SHA-256	Typical users
Lowercase hex	64 characters	GitHub, Stripe, most REST APIs
Base64	44 characters (with `=` padding)	Shopify, Slack legacy, AWS headers
Base64url	43 characters (no padding)	JWT `HS256` signature segment

A digest that “looks wrong” but is the right length in a different alphabet is an encoding bug, not a secret mismatch. For the encoding mechanics themselves see the ; for the JWT variant, the .

Computing HMAC in the Browser

SubtleCrypto supports HMAC natively, so a signature can be produced or checked with no network exposure at all:

async function hmacSha256Hex(secret, message) {
 const enc = new TextEncoder();
 const key = await crypto.subtle.importKey(
 "raw", enc.encode(secret),
 { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]
 );
 const sig = await crypto.subtle.sign("HMAC", key, enc.encode(message));
 return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
}

For verification prefer crypto.subtle.verify("HMAC", key, signatureBytes, data) — it compares internally instead of exposing you to a naive ===.

Operational Checklist

Generate keys randomly. 32 bytes from crypto.getRandomValues or openssl rand -hex 32 — never a passphrase.
Sign the exact bytes on the wire. No re-serialisation, trimming, or charset conversion.
Compare in constant time. crypto.timingSafeEqual, Python’s hmac.compare_digest, PHP’s hash_equals, or subtle.verify.
Include a timestamp and reject stale requests. HMAC proves authenticity, not freshness.
Support two active secrets during rotation. Accept either tag while migrating, then retire the old key — this is exactly why Stripe can send one v1 signature per active secret.
Never log the secret or put it in a URL. Query strings land in access logs, proxies, and browser history.

Choosing the Hash

Algorithm	Digest	Verdict for new work
HMAC-SHA256	32 bytes	Default. Universal library support, ample margin.
HMAC-SHA512	64 bytes	Fine; faster than SHA-256 on 64-bit CPUs for large payloads.
HMAC-SHA384	48 bytes	Use when a compliance profile requires it.
HMAC-SHA1	20 bytes	Legacy interop only (older GitHub `X-Hub-Signature`, TOTP). Not broken inside HMAC, but do not choose it for new protocols.

HMAC-SHA1 remains safe as an authenticator because HMAC does not depend on collision resistance — the same reason . Even so, auditors flag it, so new designs should start at SHA-256. For plain (unkeyed) integrity digests, see the .

Step-by-Step: Debugging a Failing Signature with Toolbox

Capture the raw body from your server logs or the provider’s delivery inspector — copy the exact bytes, not a pretty-printed version.
Open the tool: visit the .
Paste the payload and the signing secret, and select SHA-256.
For Stripe, prepend the timestamp: enter 1492774577.{"id":"evt_…"} — timestamp, dot, raw body — matching the signed_payload construction.
Compare digests: place the provider’s header value next to the computed digest. A hex/Base64 mismatch means an encoding bug; a completely different digest means the body was mutated or the wrong secret is in use.

Outcome: you localise the fault to one of three causes — wrong secret, mutated body, or wrong signed-payload construction — in a couple of minutes, without redeploying to add log statements.

Related guides: · ·

FAQ

Frequently Asked Questions

Why is HMAC used instead of simply hashing the secret and the message together? ▼

SHA-1 and SHA-2 are Merkle-Damgard constructions vulnerable to length extension: given H(secret || message) and the input length, an attacker can produce a valid digest for message || padding || attacker_data without knowing the secret. HMAC's nested form, H((K XOR opad) || H((K XOR ipad) || message)), prevents that, which is why RFC 2104 and FIPS PUB 198-1 specify it.

Why does webhook signature verification fail when my framework parses JSON automatically? ▼

The digest covers the exact bytes the provider sent. Body parsers re-serialise JSON and can reorder keys or change whitespace, number, and Unicode formatting, producing a different byte string and digest. Capture the raw body before parsing middleware runs — in Express, mount the webhook route before express.json() or use express.raw() on that route.

What is the difference between HMAC and a digital signature? ▼

HMAC is symmetric: the same secret creates and verifies the tag, so any verifier can also forge. It proves the sender holds the shared secret. RSA or ECDSA signatures are asymmetric — the private key signs, the public key only verifies — adding non-repudiation. Webhooks use HMAC because a shared secret already exists and HMAC is far faster.

Do I still need a timestamp check if the signature is valid? ▼

Yes. A valid signature proves authenticity and integrity, not freshness. Without a signed timestamp an intercepted request can be replayed indefinitely. Stripe signs a timestamp and its libraries default to a five-minute tolerance; where no timestamp is signed, deduplicate on the delivery or event ID.

Cron Syntax & Expression Architecture: The Complete Guide to Scheduling Jobs

Sat, 05 Sep 2026 00:00:00 +0000

Free In-Browser Tool TOOLBOX UTILITY

Cron Schedule Builder

Build, parse, and validate cron schedules with instant human-readable English descriptions and live execution timeline preview.

Open Cron Builder & Schedule Tester →

What Is Cron and Why Does Syntax Precision Matter?

Derived from the Greek word Chronos (time), cron is the universal time-based job scheduler found in Unix-like operating systems, cloud task runners (AWS EventBridge, Google Cloud Scheduler), and backend background queues (Celery, BullMQ, Sidekiq).

A misconfigured cron expression in production can lead to severe consequences:

Database backup scripts running every minute instead of every night at midnight, causing CPU exhaustion.
Billing webhooks executing twice during a Daylight Saving Time autumn rollback.
Data retention cleanups failing to execute because of contradictory day-of-month and day-of-week constraints.

Understanding the underlying grammar of cron expressions enables engineers to write deterministic, resilient background job schedules.

The 5-Field UNIX Cron Anatomy

Standard POSIX / Vixie cron expressions are composed of five distinct fields separated by white space:

 ┌───────────── Minute (0 - 59)
 │ ┌───────────── Hour (0 - 23, 24-hour clock)
 │ │ ┌───────────── Day of the Month (1 - 31)
 │ │ │ ┌───────────── Month of the Year (1 - 12 or JAN - DEC)
 │ │ │ │ ┌───────────── Day of the Week (0 - 6 or SUN - SAT)
 │ │ │ │ │
 * * * * *

Detailed Field Range Specifications

Field Position	Field Name	Allowed Values	Allowed Special Characters
1	Minute	`0 - 59`	`*` `,` `-` `/`
2	Hour	`0 - 23`	`*` `,` `-` `/`
3	Day of Month	`1 - 31`	`*` `,` `-` `/`
4	Month	`1 - 12` or `JAN - DEC`	`*` `,` `-` `/`
5	Day of Week	`0 - 6` (0 = Sunday, 6 = Saturday)	`*` `,` `-` `/`

Note on Sunday representation: In many modern implementations (including Vixie Cron, crontab on Ubuntu, and macOS), both 0 and 7 are accepted as Sunday for usability.

Special Operators Explained

Cron expressions derive their expressive power from five core syntax operators:

1. Asterisk (`*`) — The Wildcard

Matches every valid unit within the field’s permissible range.

* * * * *: Runs at the beginning of every minute of every hour, day, and month.
0 * * * *: Runs at minute 0 of every hour (i.e. once every hour on the hour).

2. Comma (`,`) — Value Lists

Defines an explicit enumeration of discrete values.

0 9,12,18 * * *: Triggers at 9:00 AM, 12:00 PM, and 6:00 PM every day.
0 0 * * 1,3,5: Runs at midnight on Mondays, Wednesdays, and Fridays.

3. Hyphen (`-`) — Value Ranges

Specifies a continuous, inclusive interval between two bounds.

0 9-17 * * *: Runs at minute 0 of every hour between 9:00 AM and 5:00 PM inclusive.
0 0 1-7 * *: Runs at midnight on the first seven days of every month.

4. Slash (`/`) — Step Values

Specifies step increments through a range. When preceded by an asterisk (*/n), it means “every n units starting from the minimum bound”.

*/15 * * * *: Runs at minutes 0, 15, 30, and 45 of every hour.
0 0/2 * * *: Runs every 2 hours (00:00, 02:00, 04:00, 06:00, …).
10-50/10 * * * *: Runs between minutes 10 and 50 in 10-minute steps (10, 20, 30, 40, 50).

5-Field Standard vs 6-Field Extended (Quartz / AWS)

While POSIX systems use the 5-field format, several popular enterprise engines (Java Quartz Scheduler, AWS CloudWatch / EventBridge, Spring Framework @Scheduled) utilize 6-field or 7-field formats:

Architecture Dimension	5-Field UNIX (POSIX / crontab)	6-Field Quartz / AWS EventBridge
Seconds Precision	❌ No (Minute is lowest granularity)	✅ Yes (Field 1 is Seconds `0-59`)
Year Specification	❌ Not supported	✅ Supported as optional 7th field (`1970-2099`)
Question Mark (`?`) Operator	❌ Throws syntax error	✅ Mandatory when specifying Day of Month or Week
`L` (Last) and `W` (Weekday)	❌ Rarely supported	✅ Fully supported (`L` = last day, `15W` = nearest weekday)
Primary Platforms	Linux `crontab`, Node.js `node-cron`, Python `Celery`	AWS EventBridge, Spring Boot, Quartz Java, Kubernetes CronJobs

Example: Quartz / AWS Syntax

In AWS EventBridge, a schedule running at 10:15 AM every weekday requires 6 fields and the ? character:

cron(0 15 10 ? * MON-FRI *)

10 Common Production Cron Recipes

Here are production-tested recipes ready to deploy for common infrastructure patterns:

Operational Objective	Standard Cron Expression	English Meaning
Health Check Heartbeat	`/5 * * *`	Every 5 minutes
Hourly Log Rotation	`0 * * * *`	Once an hour on the hour (:00)
Nightly Database Backup	`0 2 * * *`	Every day at 02:00 AM
Weekday Business Hours Task	`0 9 * * 1-5`	Monday through Friday at 09:00 AM
Weekly Maintenance Window	`0 3 * * 0`	Every Sunday at 03:00 AM
Monthly Invoice Generation	`0 0 1 * *`	1st of every month at midnight (00:00)
Quarterly Audit Report	`0 0 1 1,4,7,10 *`	1st of Jan, Apr, Jul, Oct at midnight
Twice-Daily Cache Warmup	`0 6,18 * * *`	Every day at 06:00 AM and 06:00 PM
End of Month Reconciliation	`0 23 28-31 * *`	Nightly from 28th-31st (pair with bash check)
Yearly Archival	`0 0 1 1 *`	January 1st at midnight

Critical Pitfalls & Production Best Practices

1. The Daylight Saving Time (DST) Trap

When a server is configured to a local timezone observing Daylight Saving Time:

Spring Forward (+1 hr): At 2:00 AM, the clock jumps directly to 3:00 AM. Any job scheduled for 0 2 * * * is completely skipped.
Fall Back (-1 hr): At 2:00 AM, the clock rewinds to 1:00 AM. Any job scheduled between 1:00 AM and 2:00 AM runs twice.

Solution: Always set the system timezone of worker servers and container clusters to UTC (tzdata: Etc/UTC).

2. The “Thundering Herd” Problem

If 50 different microservices schedule heavy batch jobs at exactly 0 0 * * * (midnight), database IOPS and CPU utilization will spike dramatically.

Solution: Stagger cron schedules with jitter. Run service A at 17 2 * * *, service B at 34 2 * * *, and service C at 49 2 * * *.

3. Day of Month AND Day of Week Interaction

In POSIX cron, if you specify both:

0 0 15 * 1

The job does not execute only when the 15th happens to be a Monday. It executes whenever the day is the 15th OR whenever the day is a Monday.

Step-by-Step: Generating Cron Schedules with Toolbox

Open the Tool: Visit the .
Select Frequency: Use the interactive visual controls to choose between Minute, Hourly, Daily, Weekly, Monthly, or Custom intervals.
Inspect Real-Time Translation: The engine instantly renders a plain-English translation of your schedule (e.g. “At 02:30 AM on day 1 of the month”).
Preview Next 5 Execution Dates: Verify the exact upcoming UTC and local timestamps to ensure no scheduling surprises occur.
Copy Expression: Click Copy Expression to paste the POSIX-compliant string directly into your crontab, Dockerfile, or infrastructure code.

Interactive Workbench LIVE

Cron Syntax & Expression Architecture: The Complete Guide to Scheduling Jobs

Open Fullscreen ↗

Build, parse, and validate cron schedules with instant human-readable English descriptions and live execution timeline preview.

Initializing Workbench...

100% Client-Side RAM Sandbox

🔒 Private Execution: Computations run in local browser memory. Zero server uploads. Zero server uploads.

Launch Fullscreen →

FAQ

Frequently Asked Questions

What is the standard order of fields in a 5-field cron expression? ▼

The 5 standard UNIX cron fields from left to right are: 1. Minute (0-59), 2. Hour (0-23), 3. Day of the Month (1-31), 4. Month of the Year (1-12 or JAN-DEC), and 5. Day of the Week (0-6 or SUN-SAT, where 0 and 7 usually represent Sunday).

What is the difference between * and */5 in cron syntax? ▼

An asterisk (*) matches every possible value in that field (e.g. * in the minute field means run every minute). A step value with a slash (*/5) matches every nth interval starting from the field's minimum (e.g. */5 in the minute field triggers at minutes 0, 5, 10, 15, ..., 55).

How does Daylight Saving Time (DST) affect scheduled cron jobs? ▼

If your server timezone observes DST, schedules running during the transition hour can either be skipped entirely (when clocks spring forward by 1 hour) or execute twice (when clocks fall back by 1 hour). For mission-critical background jobs and batch billing, servers and cron schedulers should always be configured to UTC.

Can I specify both Day of Month and Day of Week simultaneously? ▼

In standard UNIX cron (Vixie Cron), specifying non-wildcard values in both the Day of Month and Day of Week fields creates an OR condition rather than an AND condition. The job triggers whenever EITHER condition matches. In Quartz/AWS cron, one of these fields must be set to '?' to avoid ambiguous scheduling.

Backend | Toolbox Guides & Articles

HMAC-SHA256 Webhook Signature Verification: RFC 2104 Internals and Provider Formats

HMAC-SHA256 Webhook Signature Verification: RFC 2104 Internals and Provider Formats

HMAC Signature Generator & Verifier

The Problem HMAC Solves

The RFC 2104 Construction

Why not H(secret || message)?

Block sizes and digest lengths

Provider Formats Compared

Stripe

GitHub

Shopify

The Four Failure Modes

1. The body was parsed before you hashed it

2. Non-constant-time comparison

3. No replay protection

4. Signature comparison as the only gate

Hex, Base64, or Base64url — Match the Provider Exactly

Computing HMAC in the Browser

Operational Checklist

Choosing the Hash

Step-by-Step: Debugging a Failing Signature with Toolbox

Frequently Asked Questions

Cron Syntax & Expression Architecture: The Complete Guide to Scheduling Jobs

Cron Schedule Builder

What Is Cron and Why Does Syntax Precision Matter?

The 5-Field UNIX Cron Anatomy

Detailed Field Range Specifications

Special Operators Explained

1. Asterisk (*) — The Wildcard

2. Comma (,) — Value Lists

3. Hyphen (-) — Value Ranges

4. Slash (/) — Step Values

5-Field Standard vs 6-Field Extended (Quartz / AWS)

Example: Quartz / AWS Syntax

10 Common Production Cron Recipes

Critical Pitfalls & Production Best Practices

1. The Daylight Saving Time (DST) Trap

2. The “Thundering Herd” Problem

3. Day of Month AND Day of Week Interaction

Step-by-Step: Generating Cron Schedules with Toolbox

Cron Syntax & Expression Architecture: The Complete Guide to Scheduling Jobs

Frequently Asked Questions

Why not `H(secret || message)`?

1. Asterisk (`*`) — The Wildcard

2. Comma (`,`) — Value Lists

3. Hyphen (`-`) — Value Ranges

4. Slash (`/`) — Step Values