Verify signatures
Check the Shortcut-Signature header on every webhook request, with complete examples in Node, Python, Ruby, PHP, and Go.
After this page your receiver accepts only requests that Shortcut sent, unchanged, in the last five minutes, and refuses everything else.
Your webhook URL is public, so anyone can send it a request. The Shortcut-Signature header proves a request came from Shortcut: only Shortcut and you know the webhook's signing secret. Check it on every request, before you act on the body.
The scheme
Shortcut-Signature: t=1792249445,v1=7f4286ee39f4b09942722c368f2dd0c34e07adfb5e2cc76f949c7049ed0ad076tis when Shortcut signed the request, in Unix seconds. Each attempt is signed again, so a retry has a newt.v1is the signature: the HMAC-SHA256 of the string<t>.<raw body>, keyed with the webhook's whole secret,whsec_included, written as 64 lowercase hex characters.For 24 hours after a secret rotation, the header has two
v1values, one per secret, the new one first:t=…,v1=…,v1=…. A request is genuine when anyv1matches.
To verify a request:
Read the raw body, exactly the bytes that arrived, before any JSON parsing. A parsed and re-serialized body may differ in spacing, key order, or number formatting, and then it does not match.
Split the header on
,, then each part at its first=. Keeptand everyv1. Ignore parts you do not recognize.Check the time. Refuse the request if
tis more than 300 seconds (five minutes) away from your clock. This stops someone replaying a request they captured. Keep your server's clock synchronized.Compute the hex HMAC-SHA256 of
t, a period, and the raw body, with your secret as the key.Compare it with each
v1in constant time. Accept if one matches; otherwise answer400and do nothing.
Then drop duplicates by the envelope's id, store the event, and answer 2xx. See Retries and monitoring.
Each example below reads the secret from SHORTCUT_WEBHOOK_SECRET.
Node
With Express, express.raw keeps the body as the bytes that arrived. Mount it on the webhook route only, ahead of any express.json() that would consume the body.
In another framework, the rule is the same: hand the verifier the unparsed body as a Buffer or string.
Python
With Flask, request.get_data() returns the raw bytes. Call it before anything reads request.json.
In Django, use request.body and request.headers.get("Shortcut-Signature").
Ruby
With Sinatra or any Rack app, read the body from request.body, and compare with Rack::Utils.secure_compare.
In Rails, use request.raw_post and request.headers["Shortcut-Signature"], and ActiveSupport::SecurityUtils.secure_compare.
PHP
php://input holds the raw body; the header arrives as $_SERVER['HTTP_SHORTCUT_SIGNATURE']. PHP's hash_equals function compares in constant time.
In Laravel, use $request->getContent() and $request->header('Shortcut-Signature').
Go
Read the whole body with io.ReadAll before decoding it, and compare with hmac.Equal.
Check your code against a known signature
Run your verifier on these values with the time check turned off (they were signed in the past). The secret is an example made for this page; it signs nothing real.
Secret
whsec_docs-example-secret-000
t
1792249445
Raw body
The single line below, 348 bytes, no trailing newline.
Expected v1
7f4286ee39f4b09942722c368f2dd0c34e07adfb5e2cc76f949c7049ed0ad076
Then send a real test event to your endpoint with POST /v1/webhooks/{id}/test, and check that it answered 200. See Local development.
When verification fails
Every request fails
The body was parsed before verifying (a JSON body parser ran first), the secret is wrong or has a stray space or newline, or the whsec_ prefix was left out of the key.
Requests fail only after a rotation
The receiver has neither the new nor the previous secret. For 24 hours either one verifies; after that only the new one does.
Requests fail with an old t
Your server's clock is off by more than five minutes. Synchronize it with NTP.
Some requests fail
A proxy or framework changed the body, for example by re-encoding characters outside ASCII. Verify the bytes as they arrived.
A request that fails verification should get a 400. Shortcut counts it as a failed attempt and retries it, so a genuine event whose secret you fixed in time is delivered on a later attempt; look it up in the deliveries list.
Last updated