Setup
Setup
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 The CLI and Python SDK read
x-phelm-workspace-id. When it has more than one, export the workspace ID as well.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, withcrypto.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
- Stripe
- GitHub
- Standard Webhooks
- Other HMAC-SHA256
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’sreceivedAt 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.
Test vector
Check your verifier offline before you point it at real traffic. These values were computed with Node’s Web Crypto, Python’shmac, 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
The signature never matches
The signature never matches
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 passes but Standard Webhooks fails with the same-looking secret
Stripe passes but Standard Webhooks fails with the same-looking secret
Stripe keys the HMAC with the whole
whsec_… string. Standard Webhooks base64-decodes the part after whsec_ and uses those bytes.The timestamp check fails in a test
The timestamp check fails in a test
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.