# 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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/formspree-webhooks/examples/express/)):

```javascript
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/formspree-webhooks/examples/fastapi/)):

```python
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/formspree-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/formspree-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/formspree-webhooks/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.

```json
{
  "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

```bash
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

```bash
# 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/formspree-webhooks/references/overview.md) - Webhook types, payload, retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/formspree-webhooks/references/setup.md) - Enabling the Webhook plugin, signing secret, testing
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/formspree-webhooks/references/verification.md) - Header format, rotation, tolerance, debugging