The Standard Webhooks spec versus Shopify's HMAC header and GitLab's shared-secret token

What it is

The Standard Webhooks specification defines three headers on every delivery: webhook-id (a unique message identifier), webhook-timestamp (Unix seconds), and webhook-signature, sent as a space-delimited list of v1,<base64 signature> values "to support zero downtime secret rotation" (asymmetric v1a, entries can appear too). The signed content is msg_id.timestamp.payload, and the shared secret is "base64 encoded, prefixed with whsec_ for easy identification": the HMAC key is the base64-decoded remainder, not the text itself. GitLab's documentation states that its signing tokens (introduced in 19.0, generally available in GitLab 19.1) follow this: "GitLab webhook delivery follows the Standard Webhooks specification," and it tells receivers to strip whsec_ and base64-decode the rest. By contrast, GitLab's older mechanism, the secret token, is "sent as plain text in the X-Gitlab-Token HTTP header" — a direct string compare, not an HMAC, which GitLab's own docs now call the option with "weaker security guarantees" and no longer recommend for new webhooks. Shopify uses a third scheme entirely: a base64-encoded X-Shopify-Hmac-SHA256 header, verified by computing "HMAC-SHA256 of the raw request body using your app's client secret as the key" and comparing it "to the decoded header value". Shopify's signature has no timestamp, so there is no replay window; deduplicate on X-Shopify-Webhook-Id.

Why it matters

Three shapes of "webhook security" are in wide use, and a client library or code sample for one will silently fail on another: a shared HMAC construction (Standard Webhooks and, now, GitLab's signing token), a proprietary single-header HMAC (Shopify), and a non-cryptographic shared-secret comparison (GitLab's legacy token and similar schemes).

How to apply

• For any provider claiming Standard Webhooks compliance (GitLab's signing token is one), verify webhook-signature by recomputing HMAC-SHA256 over id.timestamp.payload keyed with the base64-decoded bytes after whsec_, base64-encoding the digest, prefixing v1,, and accepting if any space-separated entry matches in a constant-time compare; also check webhook-timestamp is recent.
• For Shopify, base64-decode the header and compare the resulting 32 bytes with the raw HMAC-SHA256 digest of the body — never a hex digest. After a client-secret rotation, Shopify may keep signing with the old secret for up to an hour.
• For GitLab's legacy X-Gitlab-Token, compare it with the configured secret token (constant-time compare still advisable) — there is no signature to recompute — and migrate to the signing token where available.
• Never treat a plain shared-secret token as equivalent to an HMAC: the token travels in every request, so anything that can read one request (a logging proxy, a TLS-terminating intermediary) can forge arbitrary payloads, while an HMAC never exposes the key and binds it to one exact body.

import base64, hashlib, hmac

def verify_standard(secret: str, msg_id: str, ts: str, raw_body: bytes, header: str) -> bool:
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = msg_id.encode() + b"." + ts.encode() + b"." + raw_body
    expected = b"v1," + base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
    return any(hmac.compare_digest(expected, s.encode()) for s in header.split(" "))

Pitfalls

Applying HMAC-verification code to a provider that only uses a shared-secret token (there is nothing to hash), or assuming a shared-secret token can be constant-time-compared away as if that closed the gap with an HMAC. Missing that GitLab now offers both mechanisms side by side on the same webhook configuration screen.