Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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=7f4286ee39f4b09942722c368f2dd0c34e07adfb5e2cc76f949c7049ed0ad076
  • t is when Shortcut signed the request, in Unix seconds. Each attempt is signed again, so a retry has a new t.

  • v1 is 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 v1 values, one per secret, the new one first: t=…,v1=…,v1=…. A request is genuine when any v1 matches.

To verify a request:

  1. 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.

  2. Split the header on ,, then each part at its first =. Keep t and every v1. Ignore parts you do not recognize.

  3. Check the time. Refuse the request if t is more than 300 seconds (five minutes) away from your clock. This stops someone replaying a request they captured. Keep your server's clock synchronized.

  4. Compute the hex HMAC-SHA256 of t, a period, and the raw body, with your secret as the key.

  5. Compare it with each v1 in constant time. Accept if one matches; otherwise answer 400 and 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.

Input
Value

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

Symptom
Likely cause

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