# 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. **Build an endpoint**

   Make a public `https` address that accepts a POST with a JSON body and answers with a 2xx status.
2. **Connect it**

   On the **Destinations** page, connect a **Webhook** with your address and a short description, such as `CRM lead intake`.
3. **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. **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. **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*

```json
{
  "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."
  }
}
```

- `event` (string, required): Always `submission.created`.
- `submission_id` (string, required): The id of the submission. Read it in full with [GET /api/v1/submissions/{id}](https://formpik.com/docs/api/submissions#one). It stays the same when the flows run again.
- `form` (object, required): The `id` and `name` of the form.
- `source` (object | null, required): The `id`, `name` and `domain` of the source it was sent to. `null` when that source has been removed since.
- `received_at` (string, required): When the submission arrived, as an ISO 8601 time in UTC.
- `data` (object, required): 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.
- `values` (object, required): 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
```

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

1. **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. **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. **Rebuild the signed text**

   Join `t`, a dot and the raw body: `1763631000.{"event":"submission.created",...}`.
4. **Compute the HMAC**

   Compute an HMAC SHA-256 of that text with your signing secret as the key, written as lowercase hex.
5. **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. **Check the time**

   Reject requests whose `t` is more than five minutes away from your clock.

*JavaScript*

```js
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)
```

*Python*

```python
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

SECRET = os.environ["FORMPIK_SIGNING_SECRET"]
TOLERANCE_SECONDS = 300

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"]
        age = abs(time.time() - int(timestamp))
    except (KeyError, ValueError):
        return False

    if age > TOLERANCE_SECONDS:
        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()  # the exact bytes, before parsing

    if not verify_formpik(raw, request.headers.get("X-Formpik-Signature", ""), SECRET):
        abort(401)

    event = json.loads(raw)
    print("New submission", event["submission_id"], event["data"].get("email"))

    return "", 204
```

*PHP*

```js
<?php

function verify_formpik(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
    $parts = [];

    foreach (explode(',', $header) as $part) {
        $pair = explode('=', $part, 2);

        if (count($pair) === 2) {
            $parts[$pair[0]] = $pair[1];
        }
    }

    if (!isset($parts['t'], $parts['v1'])) {
        return false;
    }

    if (abs(time() - (int) $parts['t']) > $tolerance) {
        return false;
    }

    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);

    return hash_equals($expected, $parts['v1']);
}

// The exact bytes, before json_decode
$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_FORMPIK_SIGNATURE'] ?? '';

if (!verify_formpik($raw, $header, getenv('FORMPIK_SIGNING_SECRET'))) {
    http_response_code(401);
    exit('Bad signature');
}

$event = json_decode($raw, true);
http_response_code(204);
```

> **Keep the secret on your server**
>
> Anyone with the signing secret can sign requests that look like Formpik's. Never put it in a web page or commit it to a repository. Each webhook destination has its own secret, and it stays the same when you change the address.

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

```js
// 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. **Find the submission**

   Open **Submissions** and filter on **Needs attention**. The failed step shows the reason.
2. **Fix the cause**

   For example a wrong address, an expired token on your side, or a server that took longer than 10 seconds.
3. **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](https://formpik.com/docs/destinations#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.

- [Read submissions](https://formpik.com/docs/api/submissions): Fetch the full submission with its runs and files.
- [Destinations](https://formpik.com/docs/destinations): Address rules, timeouts and who sees what.

---

Source: https://formpik.com/docs/webhooks
