Skip to main content
Recompute the HMAC over the exact bytes your sender sent, then compare it to the signature header. A webhook inbox keeps those bytes, so you can check your signing code, or a provider’s, in a test.
Export an API key. When the organization has one workspace, leave the workspace unset: the API uses that workspace, and the CLI and SDKs omit x-phelm-workspace-id. When it has more than one, export the workspace ID as well.
The CLI and Python SDK read DEVHELM_API_TOKEN. The TypeScript SDK takes the key in its constructor and reads DEVHELM_WORKSPACE_ID when it is set. With curl, send the workspace header only when you set the variable:

Raw bytes, not the text view

A signature covers bytes, and parsing, decoding, or re-serializing a body changes them. Verify against the raw download (raw(), devhelm inboxes events raw, or GET …/raw): the body bytes exactly as received, binary included. Never use body or text(). They are the body decoded as UTF-8, lossy for non-UTF-8 bytes and clipped at 256 KB on GET. The Python SDK’s text() docstring says signature checks use that string; use raw() instead. The raw download holds the body only. Read the signature header from event.headers, where names are lowercased and values are lists: headers["stripe-signature"][0], not Stripe-Signature. The event’s sha256 is the SHA-256 of the raw bytes, so you can check that the download is intact. It is not an HMAC.

Get the raw body and the signature header

GET …/raw returns {url, expiresAt, filename, contentType, sizeBytes}. The url is a signed link that expires after 60 seconds; request a new one if it lapses. The CLI events raw and the SDK event.raw() fetch a fresh link on every call; the SDK version is in the test below.

Verify by scheme

The verifiers use Web Crypto in TypeScript (Node 18+, Deno, Bun, edge runtimes) and the standard library in Python, with no provider SDK. Both compare in constant time, with crypto.subtle.verify and hmac.compare_digest; a plain === or == leaks timing. Save the TypeScript helpers and verifiers in one module, verify-webhook.ts, and the Python ones in verify_webhook.py.
verify-webhook.ts
Header stripe-signature: t=<unix-seconds>,v1=<hex>. The MAC is HMAC-SHA256 over <t>.<raw body>, keyed with the whole whsec_… signing secret as a string. More than one v1 appears while a secret rotates; any match passes. Stripe’s libraries reject a t more than 5 minutes (300 s) from the current time.

Assert the signature in a test

Wait for your sender’s request, then verify it. Pass the event’s receivedAt as “now” for the tolerance check, so the result does not depend on when the check runs. sendTestWebhook / send_test_webhook stands for your code under test.
To check a provider’s own signatures, register the inbox URL as a test-mode endpoint with that provider and verify with the signing secret it gives you.

Test vector

Check your verifier offline before you point it at real traffic. These values were computed with Node’s Web Crypto, Python’s hmac, and openssl dgst, and all three agree. The test also proves that a re-serialized body and a timestamp outside the tolerance both fail:

Keep the raw body in your receiver

The same rule applies in the service that receives webhooks: verify before any body parser touches the request. A re-parsed body can differ from the sent bytes in whitespace, key order, Unicode escapes (\u00e9 vs é), number formatting (1.0 vs 1), and a trailing newline, and any of these changes the MAC. Read the body once, verify, then parse those same bytes.

Troubleshooting

Hash the bytes from raw(), not body or text(). If the SHA-256 of those bytes equals the event’s sha256, the bytes are right and the problem is the secret, the signed string, or the encoding.
Stripe keys the HMAC with the whole whsec_… string. Standard Webhooks base64-decodes the part after whsec_ and uses those bytes.
The current time is more than 5 minutes from the signed timestamp, for example on an old event or the test vector. Pass the event’s receivedAt, or the vector’s timestamp, as “now”.

Next steps

Wait for a webhook in a test

Full wait semantics, the Nth event, and negative assertions.

How inboxes capture requests

Stored fields, raw download, and the events list.

Simulate a failing receiver

Check that every retry is signed again correctly.

Testing in CI

Signing secrets and the DevHelm key as CI secrets.

Limits, quotas, and errors

Body size limits, quotas, and error codes.

Wait for an email in a test

The same wait semantics for testing mailboxes.