Skip to content

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

  1. 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.
  2. Split the header on commas, then each part on the first =.
  3. Rebuild the signed text: t, a dot, then the raw body.
  4. Compute an HMAC SHA-256 of that text with your signing secret, as lowercase hex, and compare it with v1 in constant time.
  5. Reject requests whose t is 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 "", 204

Mistakes 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 timingSafeEqual or compare_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.

Keep reading

More from the blog