Verify QStash request signatures on a receiver endpoint so only genuine QStash deliveries are processed

Documented steps

1. Get QSTASH_TOKEN from the console QStash tab, and get the signing keys from the console or via GET /v2/keys with 'Authorization: Bearer <QSTASH_TOKEN>', which returns {"current":"...","next":"..."}. Store both as QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY.
2. In the handler, read the RAW request body exactly as received (never JSON.parse then re-stringify) and read the 'Upstash-Signature' header — a JWT signed with HMAC SHA256 using your current signing key.
3. Install the official SDK: @upstash/qstash (TS, Receiver class), qstash (Python, Receiver class), or github.com/qstash/qstash-go (NewReceiver).
4. TypeScript: const receiver = new Receiver({ currentSigningKey, nextSigningKey }); const isValid = await receiver.verify({ body, signature: req.headers['Upstash-Signature'], url: 'https://your-endpoint-url' }). The url must match your endpoint's public URL exactly because it is checked against the JWT 'sub' claim.
5. Next.js shortcut: wrap the handler with verifySignatureAppRouter (App Router) or the Pages Router equivalent from '@upstash/qstash/nextjs'; it loads the signing keys from env and throws if either is missing.
6. Manual verification: split the JWT into header.payload.signature, verify the HMAC SHA256 against the current signing key, retry against the next signing key if that fails (this is what makes rotation safe), then base64url-decode the payload.
7. Validate every claim: iss must equal 'Upstash'; sub must equal your endpoint's exact URL; exp must not be past; nbf must not be future; and the 'body' claim must equal the base64url-encoded SHA-256 hash of the raw request body bytes.
8. QStash JWTs have a default lifetime of 5 minutes — reject anything outside the exp/nbf window even when the HMAC checks out.
9. On any verification failure return HTTP 401 and do not process the payload; return 2xx only after verification succeeds.
10. Rotate keys via the console 'Roll keys' button or POST /v2/keys/rotate with the QStash bearer token; the old 'next' becomes the new 'current' and a fresh 'next' is generated.
11. After rotating, update QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY in every deployment and keep verifying against both keys during the rollout window so in-flight requests signed with the old key still pass.
12. Useful non-signed metadata on every delivery: Upstash-Retried (attempt count, starting at 0), Upstash-Message-Id, Upstash-Schedule-Id, Upstash-Caller-Ip, Upstash-Topic-Name — log these for idempotency after verification passes.
13. Official docs: https://upstash.com/docs/qstash/howto/signature | https://upstash.com/docs/qstash/features/security | https://upstash.com/docs/qstash/howto/roll-signing-keys | https://upstash.com/docs/qstash/howto/receiving