How to verify Formpik webhook signatures in Node.js and Python
Every Formpik webhook carries an HMAC signature. Check it in a few lines, so only real submissions reach your system.
2 min read
On this page
A webhook endpoint is a public address. Anyone who finds it can post to it, and an endpoint that trusts whatever arrives can be fed fake orders, fake leads or worse. That is why every webhook Formpik sends is signed. Checking the signature takes a few lines, and it is the difference between "a request arrived" and "Formpik sent this, and nobody changed it on the way".
What a delivery looks like
Each delivery is a JSON POST with a few headers that matter:
X-Formpik-Event: submission.created
X-Formpik-Delivery: run_2w4e6r8t0y2u:step_k3j5h7g9f1
Idempotency-Key: run_2w4e6r8t0y2u:step_k3j5h7g9f1
X-Formpik-Signature: t=1763631000,v1=5d8f0c1b9a7e2d4f...The signature header holds two parts: t, when the request was signed in Unix seconds, and v1, an HMAC SHA-256 of the signed text, made with your destination's signing secret.
Check it in five steps
- Read the raw body, exactly as it arrived. Parsing the JSON and printing it again can change spaces or key order, and then the signature no longer matches.
- Split the header on commas, then each part on the first
=. - Rebuild the signed text:
t, a dot, then the raw body. - Compute an HMAC SHA-256 of that text with your signing secret, as lowercase hex, and compare it with
v1in constant time. - Reject requests whose
tis more than five minutes away from your clock, so an old request cannot be replayed.
Node.js with Express
import crypto from "node:crypto"
import express from "express"
const SECRET = process.env.FORMPIK_SIGNING_SECRET
function verifyFormpik(rawBody, header, secret) {
const parts = Object.fromEntries(
header.split(",").map(part => {
const index = part.indexOf("=")
return [part.slice(0, index), part.slice(index + 1)]
})
)
if (!parts.t || !parts.v1) return false
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false
const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest("hex")
const a = Buffer.from(expected)
const b = Buffer.from(parts.v1)
return a.length === b.length && crypto.timingSafeEqual(a, b)
}
const app = express()
// express.raw keeps the exact bytes the signature was made from
app.post("/formpik", express.raw({ type: "application/json" }), (req, res) => {
if (!verifyFormpik(req.body, req.get("X-Formpik-Signature") ?? "", SECRET)) {
return res.status(401).send("Bad signature")
}
const event = JSON.parse(req.body.toString("utf8"))
res.sendStatus(204)
console.log("New submission", event.submission_id)
})
app.listen(3000)Python with Flask
import hashlib, hmac, json, os, time
from flask import Flask, abort, request
SECRET = os.environ["FORMPIK_SIGNING_SECRET"]
def verify_formpik(raw_body: bytes, header: str, secret: str) -> bool:
try:
parts = dict(part.split("=", 1) for part in header.split(","))
timestamp, received = parts["t"], parts["v1"]
if abs(time.time() - int(timestamp)) > 300:
return False
except (KeyError, ValueError):
return False
signed = timestamp.encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received)
app = Flask(__name__)
@app.post("/formpik")
def formpik():
raw = request.get_data()
if not verify_formpik(raw, request.headers.get("X-Formpik-Signature", ""), SECRET):
abort(401)
event = json.loads(raw)
return "", 204Mistakes that break the check
- Parsing before verifying. Body parsers that turn JSON into an object throw away the exact bytes. Keep the raw body for the check, then parse.
- Comparing with ==. A plain string comparison can leak how much of a signature matched. Use
timingSafeEqualorcompare_digest. - Doing the slow work first. Answer quickly with a
2xx, then do the heavy lifting, so the delivery is not counted as failed while your code is still busy.
Keep the secret on your server
Anyone with the signing secret can sign requests that look like Formpik's. Keep it in your server's environment, never in a web page or a repository. Each webhook destination has its own secret, and it stays the same when you change the destination's address. Use the Idempotency-Key header to recognise a delivery you have already handled.
The webhooks guide has the full payload and a PHP version of the check.