Agent skill
Formspree Webhooks Skill
Receive and verify Formspree webhooks. Use when setting up Formspree webhook handlers for form submissions, debugging Formspree-Signature verification (HMAC-SHA256 hex over "<t>.<raw body>", t=<unix>,v1=<hex> header), handling retries and duplicate submissions, or dealing with Build Hook and REST Hook deliveries.
Install this skill
npx skills add hookdeck/webhook-skills --skill formspree-webhooks
When to Use This Skill
- How do I receive Formspree webhooks for form submissions?
- How do I verify the
Formspree-Signatureheader? - Why does my Formspree signature verification fail (body-only HMAC, re-serialised JSON)?
- How do I handle Formspree retries and duplicate submissions?
- What does a Build Hook or REST Hook delivery look like?
Verification (core)
Every signed delivery carries:
Formspree-Signature: t=<unix seconds>,v1=<hex>
The signature is lowercase hex HMAC-SHA256 over <t>.<raw body>: the t value exactly as it appears in the header, a literal ., then the raw body bytes. The key is the webhook's signing secret as UTF-8 bytes (not decoded). The header may carry several v1= entries (key rotation): accept when any matches and ignore other keys such as v0. Respond 401 when the header is missing, malformed or wrong.
Node (from examples/express/):
const HEX_64 = /^[0-9a-fA-F]{64}$/;
const { timestamp, timestampCount, signatures } = parseSignatureHeader(header); // t=…, every v1=…
if (timestampCount !== 1 || !timestamp) return { valid: false };
const candidates = signatures.filter((sig) => HEX_64.test(sig)); // validate before decoding
const expected = crypto
.createHmac('sha256', secret) // secret string -> UTF-8 bytes
.update(`${timestamp}.`)
.update(rawBody) // Buffer, never re-serialised JSON
.digest();
let matched = false;
for (const sig of candidates) {
matched = crypto.timingSafeEqual(Buffer.from(sig.toLowerCase(), 'hex'), expected) || matched;
}
Python (from examples/fastapi/):
candidates = [s.lower().encode("ascii") for s in signatures if _HEX_64.fullmatch(s)]
expected = hmac.new(
secret.encode("utf-8"),
timestamp.encode("utf-8") + b"." + raw_body, # raw_body is bytes from await request.body()
hashlib.sha256,
).hexdigest().encode("ascii")
matched = False
for candidate in candidates:
matched = hmac.compare_digest(expected, candidate) or matched
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
Timestamp window is opt-in
Don't reject old timestamps by default. Hookdeck retries and replays resend the original headers, so a fixed window would reject legitimate redeliveries. The examples read FORMSPREE_ (t is Unix seconds; unset or 0 = off) if you want replay protection.
Gotchas
- Formspree does not sign just the body. Computing HMAC over the body alone fails.
- Use the raw bytes:
express.raw({ type: '*/*' }),await request.arrayBuffer(),await request.body(). Parse JSON only after the check. - Compare only the
v1hex digest, not the whole header, and use the webhook's signing secret rather than an API key. - Formspree's docs sample uses
parseInt(t)when building the signed string; use thetstring as received so it always matches.
Payload and Events
There is no event-name field or header: every delivery is a new submission. The examples call it form_submission in logs only; Formspree sends no such string.
{
"form": "<form hashid>",
"keys": ["name", "email", "message"],
"submission": { "_date": "2026-10-26T10:00:00", "name": "Ada", "email": "ada@example.com", "message": "Hello" }
}
keys lists the field names in submission order. Build Hooks send an empty body (still signed). Treat every field as untrusted after verifying: check types before reading into nested values.
Delivery and Idempotency
- Return
2xxwithin 3 seconds; any other status or a timeout is retried up to 10 times. - Retries can duplicate a submission and the payload has no delivery id. The examples dedupe on a SHA-256 of the raw body (retries resend identical bytes); use a shared store in production.
- Save or queue the submission first, then return
2xx; a failure after a2xxis not retried. - The method is
POST.
Environment Variables
FORMSPREE_WEBHOOK_SECRET=your_formspree_signing_secret # UTF-8 bytes, as shown in Formspree
FORMSPREE_WEBHOOK_TOLERANCE_SECONDS=300 # Optional; unset or 0 = no window
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 formspree --path /webhooks/formspree
Use the public URL as the webhook URL in the form's Webhook plugin. Hookdeck's Formspree source verifies the signature before forwarding.
Reference Materials
- references/overview.md - Webhook types, payload, retries
- references/setup.md - Enabling the Webhook plugin, signing secret, testing
- references/verification.md - Header format, rotation, tolerance, debugging