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-Signature header?
  • 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_WEBHOOK_TOLERANCE_SECONDS (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 v1 hex 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 the t string 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 2xx within 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 a 2xx is 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →