Gareth Wilson Gareth Wilson

Guide to Formspree Webhooks: Features and Best Practices

Published


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

FeatureDetails
Signaturehex HMAC-SHA256
Signature headerformspree-signature
BodyJSON

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:

FieldMeaning
formThe form's hashid
keysField names in submission order
submissionThe fields, plus _date

Formspree's example:

{
  "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 and submit the form:

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

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:

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 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 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 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 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 for free and handle Formspree webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.