Every webhook delivery is signed with HMAC-SHA256 over the timestamp and the raw request body, joined by a dot. Verify before you trust.
Header
X-Formspring-Signature: t=1751328000,v1=5b8ad...e3
t is the Unix timestamp the delivery was signed at. v1 is the hex-encoded
HMAC-SHA256 of the string <t>.<raw body>, keyed with your webhook secret.
Parse both parts, recompute, and compare in constant time. Reject a delivery
whose t is far outside your own tolerance window to stop replays.
Read the body as raw bytes. Re-serializing the parsed JSON changes the bytes and the signature will not match.
Verify in Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';
export default function handler(req, res) {
const header = req.headers['x-formspring-signature'] ?? '';
const m = /t=(\d+),v1=([a-f0-9]+)/.exec(header);
if (!m) return res.status(401).end();
const [, t, sig] = m;
const expected = createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(`${t}.${req.rawBody}`)
.digest('hex');
if (
sig.length !== expected.length ||
!timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
) {
return res.status(401).end();
}
// safe to use req.body now
}
Verify in PHP
$header = (string) $request->header('X-Formspring-Signature');
if (! preg_match('/t=(\d+),v1=([a-f0-9]+)/', $header, $m)) {
abort(401);
}
[$_, $timestamp, $signature] = $m;
$expected = hash_hmac('sha256', $timestamp.'.'.$request->getContent(), env('WEBHOOK_SECRET'));
if (! hash_equals($expected, $signature)) {
abort(401);
}
Verify in Python
import hmac, hashlib, re
m = re.search(r"t=(\d+),v1=([a-f0-9]+)", request.headers["X-Formspring-Signature"])
if not m:
return 401
timestamp, signature = m.group(1), m.group(2)
expected = hmac.new(
secret.encode(), f"{timestamp}.".encode() + body_bytes, hashlib.sha256
).hexdigest()
if not hmac.compare_digest(expected, signature):
return 401
Verify in Ruby
m = /t=(\d+),v1=([a-f0-9]+)/.match(signature_header)
halt 401 unless m
timestamp, signature = m[1], m[2]
expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")
unless Rack::Utils.secure_compare(expected, signature)
halt 401
end
Why constant-time compare
A naive == leaks information about how many bytes matched, which an attacker can use to forge signatures one byte at a time. Use timingSafeEqual / hash_equals / compare_digest / secure_compare instead.
Key ids and several signatures
Every delivery also carries X-Formspring-Key-Id, the id of the key that signed it (whk_ plus 12 characters, derived from the secret and safe to log). The webhook object in the API shows the same id as signing_key_id, so you can see which secret a receiver is configured with without ever reading the secret.
While a rotation is in progress the signature header carries two v1 values, the previous secret first, and X-Formspring-Key-Id lists both ids in the same order:
X-Formspring-Signature: t=1751328000,v1=5b8ad...e3,v1=9c01f...7a
X-Formspring-Key-Id: whk_3f9a1c20b7de,whk_a84d02c19e55
Verify against every v1 value and accept the delivery if any one matches. The official TypeScript, PHP and Python helpers already do this. If you wrote your own check from the snippets above that read only the first v1, update it before you rotate: switch the regular expression to collect all v1= values.
const values = [...header.matchAll(/v1=([a-f0-9]+)/g)].map((m) => m[1]);
const ok = values.some((sig) => sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected)));
preg_match_all('/v1=([a-f0-9]+)/', $header, $m);
$ok = collect($m[1])->contains(fn ($sig) => hash_equals($expected, $sig));
values = re.findall(r"v1=([a-f0-9]+)", header)
ok = any(hmac.compare_digest(expected, sig) for sig in values)
Rotate the secret
Rotate without dropping a delivery:
- Call
POST /api/v1/forms/{form}/webhooks/{webhook}/rotate-secret(or therotate_webhook_secrettool). The response shows the new secret once. The old secret keeps signing foroverlap_hours(default 24, at most 168). - Deploy the new secret to your receiver. Because deliveries carry both signatures during the overlap, receivers on the old secret and receivers on the new one both keep verifying.
- When your receiver is switched, call
DELETE /api/v1/forms/{form}/webhooks/{webhook}/previous-secretto stop the old secret early, or just wait for the overlap to end.
Survey, funnel and board webhooks rotate the same way: POST /api/v1/surveys/{survey}/webhooks/{webhook}/rotate-secret, POST /api/v1/funnels/{funnel}/webhooks/{webhook}/rotate-secret and POST /api/v1/feedback-boards/{board}/webhooks/{webhook}/rotate-secret (tools rotate_survey_webhook_secret, rotate_funnel_webhook_secret and rotate_feedback_webhook_secret), each with a DELETE .../previous-secret to end the overlap early.
In the dashboard, open the webhook (form, survey or funnel) or the board's webhook list and use Rotate secret: pick how long the old secret keeps signing, confirm, and copy the new secret from the panel. It is shown once. End overlap now stops the old secret early. Every rotation, from the dashboard, the API or an agent, is recorded in the audit log with the key ids and never the secret.
If a secret leaked, send overlap_hours: 0: the old secret stops signing immediately and deliveries are signed only with the new one. Provider integrations (Slack, Sheets and so on) are not signed with a Formspring secret and cannot be rotated this way.
