# Guide to Formspree Webhooks: Features and Best Practices

Formspree gives static sites and front-end apps a form endpoint without a server: point a form's `action` at Formspree and submissions are stored, emailed and filtered for spam. The Webhook plugin, on Professional and Business plans, sends each new submission to a URL of your choice as well, so a contact form can open a support ticket, add a lead to a CRM or trigger a site rebuild.

This guide explains the three kinds of Formspree hook, the submission payload, how to verify a `Formspree-Signature` that signs a timestamp as well as the body, and how to stay inside Formspree's 3-second deadline.

## What are Formspree webhooks?

The Webhook plugin is configured per form. When you enable it, Formspree asks which type you want:

* **Simple Webhook** posts each submission as JSON. This is the type to choose for new integrations.
* **Build Hook** posts an empty body, intended for services such as Netlify that start a build when called.
* **REST Hook** follows the REST Hooks protocol, which Formspree describes as sunset and supports only for existing integrations. It sends a confirmation request with an `X-Hook-Secret` header before any submissions, and your endpoint has to echo that header back.

A webhook fires on every new submission received by the form. There are no other triggers and no event name, so a receiver never needs to route by type.

## Formspree webhook features

| Feature | Details |
| --- | --- |
| Signature | hex HMAC-SHA256 |
| Signature header | `formspree-signature` |
| Body | JSON |

Beyond the table:

* The header takes the form `t=<unix>,v1=<hex>`, and the HMAC covers `{t}.{raw_body}`.
* The signing secret comes from the webhook's settings in Formspree. Your API key won't work.
* Formspree waits 3 seconds for a `2xx` and retries a failed delivery up to 10 times.
* Formspree doesn't say whether Build Hooks are signed, and publishes no source IP addresses.

## Events and payloads

Every Simple Webhook and REST Hook delivery has the same three fields:

| Field | Meaning |
| --- | --- |
| `form` | The form's hashid |
| `keys` | Field names in submission order |
| `submission` | The fields, plus `_date` |

Formspree's example:

```json
{
  "form": "",
  "keys": ["keys", "in", "the", "order", "they", "were", "submitted"],
  "submission": {
    "_date": "2029-12-31T00:00:00",
    "field": "value",
    "other-fields": "other value"
  }
}

```

The contents of `submission` are whatever the visitor sent, named after your form's inputs. Use `keys` if you need the original field order, for example to render the submission in a ticket. Treat every value as untrusted input: a valid signature proves the request came from Formspree, not that a visitor typed a valid email address.

## Setting up Formspree webhooks

1. Open the form in Formspree and go to its **Plugins** settings. You'll need a Professional or Business plan.
2. Enable the **Webhooks** plugin and choose **Simple Webhook**.
3. Enter your endpoint URL, for example `https://example.com/webhooks/formspree`.
4. Copy the webhook's signing secret into your server's configuration, for example as `FORMSPREE_SIGNING_SECRET`.

To put Hookdeck in front, create a source with the Formspree type, set the signing secret as its verification secret, and use the source URL in step 3. Keep to Simple Webhooks in that case. A REST Hook's confirmation request expects the `X-Hook-Secret` header echoed back by the receiver, and a Hookdeck source does not do that.

While building the receiver, forward the source to your machine with the [Hookdeck CLI](/docs/cli) and submit the form:

```bash
npx hookdeck-cli listen 3000 formspree --path /webhooks/formspree

```

## Securing Formspree webhooks

Formspree signs the timestamp and the body together. Read `t` and `v1` from `Formspree-Signature`, build `{t}.{raw_body}` with the `t` string exactly as received, compute a hex HMAC-SHA256 with the signing secret, and compare it with `v1` in constant time. The [signature verification article](https://help.formspree.io/articles/advanced-features/verify-webhook-signatures) lists the usual mistakes: signing only the body, verifying re-serialised JSON, comparing against the whole header, and using the wrong secret.

### Node.js verification

```javascript
const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['formspree-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const parts = signature.split(',').map((part) => part.trim());
  const times = parts.filter((part) => part.startsWith('t=')).map((part) => part.slice(2));
  if (times.length !== 1 || !/^[0-9]+$/.test(times[0])) return false;
  const message = Buffer.concat([Buffer.from(`${times[0]}.`, 'utf8'), rawBody]);
  const candidates = parts.filter((part) => part.startsWith('v1=')).map((part) => part.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

This function checks authenticity only. Formspree's own samples also reject a `t` more than 300 seconds old and describe that check as optional. If you add it, remember that a delivery replayed later keeps its original `t`.

Because a delivery has no ID, the handler below derives one from the signed timestamp and body, then stores the submission before answering:

```javascript
const express = require('express');
const crypto = require('node:crypto');

const app = express();

app.post('/webhooks/formspree', express.raw({ type: '*/*' }), async (req, res) => {
  const signingSecret = process.env.FORMSPREE_SIGNING_SECRET;
  if (!signingSecret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, signingSecret)) return res.sendStatus(401);

  let payload;
  try {
    payload = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }
  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return res.sendStatus(400);
  const { form, keys, submission } = payload;
  if (!Array.isArray(keys) || !submission || typeof submission !== 'object') return res.sendStatus(400);

  const dedupeKey = crypto.createHash('sha256').update(req.body).digest('hex');
  try {
    await saveSubmission(dedupeKey, {
      form,
      fields: keys.map((name) => [name, submission[name]]),
      submittedAt: submission._date,
    });
  } catch {
    return res.sendStatus(503);
  }

  res.sendStatus(200);
});

```

`saveSubmission` should ignore a key it has already stored. Hashing the body, as the Formspree skill examples do, matches a retried delivery but would also merge two genuinely identical submissions made in the same second, which is usually what you want for a form.

Hookdeck's Formspree source checks the same `{t}.{raw_body}` HMAC and does not impose an age limit. It answers Formspree with `200` and records a signature mismatch as failed verification rather than returning `401`.

> **Make Formspree webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) replies to Formspree within its 3-second limit, keeps a copy of every submission and lets you replay any that your CRM or ticketing system rejected.

## Formspree webhook limitations and pain points

### A 3-second deadline

**The Problem:** A handler that creates a ticket or calls a CRM before replying times out and triggers retries.

**Why It Happens:** Formspree treats anything other than a `2xx` within 3 seconds as a failure.

**Workarounds:**

* Save or queue the submission, return `2xx`, then do the slow work.
* Remember that a background task that fails after you've replied won't be retried by Formspree.

**How Hookdeck Can Help:** Hookdeck accepts the submission from Formspree immediately and delivers it to your service with the timeout and retry policy you configure.

### Retries create duplicates, with no ID to spot them

**The Problem:** The same submission can create two tickets or two leads.

**Why It Happens:** Formspree retries up to 10 times, and a slow `2xx` can still lead to a retry. The payload has no delivery or submission ID.

**Workarounds:**

* Hash the raw body, or `t` plus the body, and refuse keys you've already processed.
* Upsert into your CRM on a natural key such as the submitted email address.

**How Hookdeck Can Help:** Hookdeck's deduplication can drop repeated requests with identical bodies before they reach your service.

### REST Hooks need a handshake

**The Problem:** A REST Hook webhook stays unconfirmed if the endpoint doesn't respond correctly to the first request.

**Why It Happens:** REST Hooks begin with a confirmation request carrying `X-Hook-Secret`, and the receiver must return that header on an empty `2xx`.

**Workarounds:**

* Choose Simple Webhook for anything new. Formspree recommends it.
* If you must use a REST Hook, add a branch that echoes `x-hook-secret` before the signature check, as Formspree's Cloudflare Worker example does.

**How Hookdeck Can Help:** Use a Simple Webhook with a Hookdeck source, which needs no handshake, and Hookdeck verifies every submission's signature.

### Build Hooks carry no data

**The Problem:** A Build Hook tells you that a submission happened but not what it contained.

**Why It Happens:** Build Hooks send an empty body by design, and Formspree's documentation doesn't say whether they're signed.

**Workarounds:**

* Use a Build Hook only to start a build, and keep a Simple Webhook for anything that needs the submission.
* Test with your own form before relying on a signature check for Build Hooks.

**How Hookdeck Can Help:** Hookdeck's request log shows exactly what a Build Hook sends, headers included, so you can confirm its behaviour before wiring it to your build service.

## Best practices

### Keep the timestamp as text

Build the signed message from the `t` value exactly as it appears in the header. Converting it to a number and back can change it and break the HMAC.

### Reply before you integrate

Write the submission to a queue or table and return `200`, then call the CRM or helpdesk from a worker. [Why asynchronous processing matters for webhooks](/webhooks/guides/why-implement-asynchronous-processing-webhooks) explains the pattern.

### Derive your own idempotency key

With no ID in the payload, a hash of the signed content is the most reliable key. The [webhook idempotency guide](/webhooks/guides/implement-webhook-idempotency) covers recording it in the same transaction as the work.

### Validate submitted fields

Field names and values come from whoever filled in the form. Check types and lengths, and keep personal data out of routine logs.

## Conclusion

A Formspree Simple Webhook sends one JSON payload per submission, signed over the timestamp and body in `Formspree-Signature`. Verify against the raw bytes, answer within 3 seconds, and deduplicate on a key you derive yourself, because Formspree's 10 retries come without a delivery ID.

[Hookdeck Event Gateway](https://hookdeck.com) sits between your forms and your back office, so a slow CRM or a failed deploy doesn't cost you submissions.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Formspree webhooks reliably in minutes.