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
- 01
Build an endpoint
Make a publichttpsaddress that accepts a POST with a JSON body and answers with a 2xx status. - 02
Connect it
On the Destinations page, connect a Webhook with your address and a short description, such asCRM lead intake. - 03
Copy the signing secret
Choose Edit on the webhook. Owners and admins see its Signing secret, which starts withwhsec_. Store it on your server, for example asFORMPIK_SIGNING_SECRET. - 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. - 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:
{
"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
idandnameof the form. sourceobject | nullrequired- The
id,nameanddomainof the source it was sent to.nullwhen 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
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| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | Formpik/1.0 |
X-Formpik-Event | submission.created |
X-Formpik-Delivery | A 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-Key | The same value as X-Formpik-Delivery, for tools that drop repeats by this header. |
X-Formpik-Signature | t=<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:
- 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. - 02
Split the header
SplitX-Formpik-Signatureon commas, then each part on the first=.tis the time of signing in Unix seconds,v1is the signature. - 03
Rebuild the signed text
Joint, a dot and the raw body:1763631000.{"event":"submission.created",...}. - 04
Compute the HMAC
Compute an HMAC SHA-256 of that text with your signing secret as the key, written as lowercase hex. - 05
Compare in constant time
Compare it withv1using a constant time comparison, such ascrypto.timingSafeEqual,hmac.compare_digestorhash_equals, and reject the request with a 401 when they differ. - 06
Check the time
Reject requests whosetis more than five minutes away from your clock.
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.
tis 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-Deliveryyou 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 onsubmission_idinstead.
// 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:
- 01
Find the submission
Open Submissions and filter on Needs attention. The failed step shows the reason. - 02
Fix the cause
For example a wrong address, an expired token on your side, or a server that took longer than 10 seconds. - 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?
Can I get the uploaded files in the webhook?
data holds the file names. Open the files from the submission in your inbox.Which should I read, data or values?
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.