Skip to content

Connect

Webhooks

A Send webhook step posts every submission that reaches it to your address as JSON, signed with a secret only you and Formpik know, so you can be sure it came from Formpik.

On this page you will learn

  • The full payload, field by field
  • Every header Formpik sends
  • How to check the signature in Node, Python and PHP
  • How to guard against replays and repeats
  • What counts as delivered and what happens when it fails

Set up a webhook

  1. 01

    Build an endpoint

    Make a public https address that accepts a POST with a JSON body and answers with a 2xx status.
  2. 02

    Connect it

    On the Destinations page, connect a Webhook with your address and a short description, such as CRM lead intake.
  3. 03

    Copy the signing secret

    Choose Edit on the webhook. Owners and admins see its Signing secret, which starts with whsec_. Store it on your server, for example as FORMPIK_SIGNING_SECRET.
  4. 04

    Add the step to a flow

    Add a Send webhook step where the submission should be sent and pick the webhook under Send to.
  5. 05

    Send a real submission

    Test runs only simulate the step. Post one real submission and check the run in the inbox: the step shows the status your server answered and how long it took.

The payload

Every delivery is a POST with this JSON body. This one is for a Contact form whose flow has an Ask AI step that saves its answer as summary:

POST body
{
  "event": "submission.created",
  "submission_id": "sub_7k2m9x4q1w3e5r6t",
  "form": {
    "id": "frm_q8w2e4r6t1y3",
    "name": "Contact"
  },
  "source": {
    "id": "src_m3n5b7v9c1x2",
    "name": "Marketing site",
    "domain": "yourcompany.com"
  },
  "received_at": "2026-11-20T09:30:00.000Z",
  "data": {
    "full_name": "Jane Cooper",
    "email": "jane@example.com",
    "topic": "sales",
    "message": "We would like a new website for our team. Could we talk next week?",
    "brief": "brief.pdf"
  },
  "values": {
    "full_name": "Jane Cooper",
    "email": "jane@example.com",
    "topic": "Sales",
    "message": "We would like a new website for our team. Could we talk next week?",
    "brief": "brief.pdf",
    "summary": "Jane Cooper wants to talk to sales about a new website next week."
  }
}
eventstringrequired
Always submission.created.
submission_idstringrequired
The id of the submission. Read it in full with GET /api/v1/submissions/{id}. It stays the same when the flows run again.
formobjectrequired
The id and name of the form.
sourceobject | nullrequired
The id, name and domain of the source it was sent to. null when that source has been removed since.
received_atstringrequired
When the submission arrived, as an ISO 8601 time in UTC.
dataobjectrequired
The answers exactly as they were sent: option values such as sales, numbers as text, lists as arrays, and file names for file fields. Use this for anything a machine reads.
valuesobjectrequired
Every answer as people read it, as text: option labels such as Sales, lists joined with commas, and an empty string for fields of the form that were left empty. It also holds the values earlier steps of the flow made with Set values and Ask AI, under their keys.

Answers whose names start with _ are left out of values. Files are never part of the payload: open them from the submission in your inbox.

Headers

Request headers
POST /formpik HTTP/1.1
Host: api.yourcompany.com
Content-Type: application/json
User-Agent: Formpik/1.0
X-Formpik-Event: submission.created
X-Formpik-Delivery: run_2w4e6r8t0y2u:step_k3j5h7g9f1
Idempotency-Key: run_2w4e6r8t0y2u:step_k3j5h7g9f1
X-Formpik-Signature: t=1763631000,v1=5d8f0c1b9a7e2d4f6a3c8b1e0d9f7a6c5b4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c
HeaderValue
Content-Typeapplication/json
User-AgentFormpik/1.0
X-Formpik-Eventsubmission.created
X-Formpik-DeliveryA unique id for this delivery, made from the run id and the step id. Running the flows again makes a new run, so it gets a new id.
Idempotency-KeyThe same value as X-Formpik-Delivery, for tools that drop repeats by this header.
X-Formpik-Signaturet=<unix seconds>,v1=<hex HMAC SHA-256>. See below.

Check the signature

The signature proves the request came from Formpik and was not changed on the way. To check it:

  1. 01

    Read the raw body

    Use the body exactly as it arrived, before any JSON parsing. Parsing and printing it again can change spaces or the order of keys, and the signature no longer matches.
  2. 02

    Split the header

    Split X-Formpik-Signature on commas, then each part on the first =. t is the time of signing in Unix seconds, v1 is the signature.
  3. 03

    Rebuild the signed text

    Join t, a dot and the raw body: 1763631000.{"event":"submission.created",...}.
  4. 04

    Compute the HMAC

    Compute an HMAC SHA-256 of that text with your signing secret as the key, written as lowercase hex.
  5. 05

    Compare in constant time

    Compare it with v1 using a constant time comparison, such as crypto.timingSafeEqual, hmac.compare_digest or hash_equals, and reject the request with a 401 when they differ.
  6. 06

    Check the time

    Reject requests whose t is more than five minutes away from your clock.
JavaScript
import crypto from "node:crypto"
import express from "express"

const SECRET = process.env.FORMPIK_SIGNING_SECRET
const TOLERANCE_SECONDS = 300

// rawBody is the request body exactly as it arrived, before any JSON parsing
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)) > TOLERANCE_SECONDS) 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, which the signature is 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"))

  // Answer quickly, then do the slow work
  res.sendStatus(204)
  console.log("New submission", event.submission_id, event.data.email)
})

app.listen(3000)

Replays and repeats

A valid signature only shows that Formpik made the request at some point. Two more checks keep old or repeated requests out:

  • Check the timestamp. t is part of the signed text, so it cannot be changed without breaking the signature. Rejecting anything older than five minutes means a request someone recorded cannot be sent to you again later. Keep your server clock in sync.
  • Remember delivery ids. Store each X-Formpik-Delivery you handled and skip ones you have seen. This also covers a request that arrives twice because a network answered late.
  • Decide what a repeat means to you. Run flows again sends a new delivery with a new id for the same submission_id. If your system must create one record per submission, key it on submission_id instead.
JavaScript
// Keep a record of every delivery you handled, for example in a table
// with a unique column. Return early when you have seen the id before.
const delivery = req.get("X-Formpik-Delivery")

if (await db.deliveries.exists(delivery)) {
  return res.sendStatus(204)
}

await db.deliveries.insert(delivery)

Answering

  • Answer with any 2xx status within 10 seconds. The body of your answer is not read for success.
  • Anything else, or no answer in time, marks the step as failed. The run history shows the status and the first 300 characters of your answer, so put a useful error message in it.
  • Redirects are not followed: a 3xx answer counts as a failure. Give the final address.
  • A failed step stops the steps after it on the same path, and the submission is marked Needs attention.
  • Do slow work, such as calling other services, after you answer, or in a background job.

Retries

Formpik does not retry failed deliveries on its own. To deliver again once your server is fixed:

  1. 01

    Find the submission

    Open Submissions and filter on Needs attention. The failed step shows the reason.
  2. 02

    Fix the cause

    For example a wrong address, an expired token on your side, or a server that took longer than 10 seconds.
  3. 03

    Run flows again

    Open the submission and choose Run flows again (editors and up). Every live flow of the form runs again for real, so your webhook gets a new delivery with a new X-Formpik-Delivery id, and the other steps of those flows send again too.

With Delivery problems on under Settings, owners and admins get an email when a delivery fails. See Email alerts.

Common questions

My signature never matches. What is wrong?
Almost always the body. Most frameworks parse JSON before your code runs, and the parsed body printed again is not the same text. Read the raw bytes, as the examples do. Also check you use the secret of this webhook and sign t, a dot, then the body.
Can I get the uploaded files in the webhook?
No. data holds the file names. Open the files from the submission in your inbox.
Which should I read, data or values?
Read data for logic and storage: it holds stable option values. Use values for text people read, and for the results of Set values and Ask AI steps.
Does a test submission call my webhook?
No. Test submissions and test runs in the flow editor only simulate the step. Post a real submission to the endpoint instead.
Can I point a webhook at Zapier or Make?
Yes. Paste their catch hook address as the webhook address. It must be a public https address, like any other.