Formy webhooks: payload, X-Formy-Signature and retries

1. Open the form and its אינטגרציות tab, and click הוספת אינטגרציה.
2. Choose התראת Webhook.
3. Paste your endpoint into כתובת ה-Webhook. It must be an https:// address.
4. Open הגדרות מתקדמות to set a סוד ה-Webhook (at least 12 characters) and up to 10 כותרות מותאמות.
5. Save, and submit a test response. Every attempt is listed under אירועים קודמים on the webhook's card.

To send only some responses, add a condition under מתי האינטגרציה תרוץ?. A response that does not meet it is not sent, and the history records it as skipped.

A partial save (the respondent has not finished) sends nothing. Neither does a deletion: Formy has no delete event.

This is a real delivery for a synthetic response, as the code sent it: a form with a text field, an email, a select, a number and a hidden field, opened from a link carrying utm_source, utm_campaign and gclid.

{
  "form_id": 1,
  "form_title": "Service agreement",
  "form_slug": "service-agreement",
  "submission": {
    "Full name": "Dana Cohen",
    "Email": "dana@example.com",
    "Package": "Package 2",
    "Monthly fee": 13000,
    "Client ID": "C-1042"
  },
  "data": {
    "3f6c2a1e-8b4d-4c2f-9a71-1d2e3f4a5b6c": { "value": "Dana Cohen", "name": "Full name", "type": "text" },
    "7b1e9c40-2d3a-4f5b-8c6d-0e1f2a3b4c5d": { "value": "dana@example.com", "name": "Email", "type": "email" },
    "8a1d4e2b-5c3f-4a6e-b7d8-9e0f1a2b3c4d": { "value": "Package 2", "name": "Package", "type": "select" },
    "c4b3a2d1-6e5f-4d7c-8b9a-0f1e2d3c4b5a": { "value": 13000, "name": "Monthly fee", "type": "number" },
    "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9": { "value": "C-1042", "name": "Client ID", "type": "text" }
  },
  "message": "השדה `submission` מיושן ויוסר בעתיד. אין להשתמש בו יותר.",
  "submission_id": 1,
  "attribution": {
    "utm_source": "newsletter",
    "utm_campaign": "autumn",
    "gclid": "abc123"
  }
}

Hidden fields are included. Layout blocks (headings, text, images, page breaks) are not, because they hold no answer. A field the respondent left empty is left out of data.

When the respondent arrived from a link with campaign parameters, attribution carries them, separate from the answers, so you can route a lead by campaign without adding a field for it. Formy records these 16 parameters and no others:

utm_source
utm_medium
utm_campaign
utm_id
utm_term
utm_content
utm_source_platform
utm_creative_format
utm_marketing_tactic
gclid
gbraid
wbraid
dclid
fbclid
ttclid
msclkid

• It is first-touch: the parameters from the visit that started the response. Later visits do not overwrite them.
• A value longer than 2,048 characters, or an empty one, is dropped. An unknown parameter is ignored.
• In an embedded form, the parameters are read from the page that hosts the form, through the embed SDK.
• Attribution is recorded whether or not the respondent agreed to analytics, because it is part of the link they clicked, not something measured about them. It is not recorded on a form using the "שאלון מוגן" privacy preset.
• The key is absent when there is nothing to report.

Formy also shows these values as columns in the responses table and its exports. Measuring the visit itself, with your own GA4, Meta Pixel or GTM, is a separate setting: see conversion tracking.

An upload field's value is a list of signed links to the files. A link stops working after 24 hours by default; a workspace admin can choose 3, 7, 14 or 30 days under תוקף קישורים לקבצים in the workspace's אבטחה ונתונים settings. Each retry signs its links afresh. Download the files when the delivery arrives rather than storing the links.

To include the response's PDF, set the form's PDF setting צירוף לאוטומציות to להוסיף קישור הורדה בלבד, which adds pdf_url (a signed link valid for 7 days), or להוסיף קישור ואת הקובץ עצמו (Base64), which also adds the file itself as pdf_base64. Formy waits up to about 30 seconds for the PDF to be ready; if it is not, the delivery goes out without it.

With a secret set, every request is signed. Verify X-Formy-Signature: it proves the request came from Formy, that the body was not changed, and when it was sent, so a captured request cannot be replayed later.

1. Split the header on , into t (a Unix timestamp in seconds) and v1 (the signature).
2. Reject the request if t is more than 5 minutes away from your clock.
3. Compute HMAC-SHA256 with your secret over t, a period (.) and the raw request body, and hex-encode it.
4. Compare the result with v1 in constant time. Reject the request if they differ.

const express = require('express')
const crypto = require('crypto')

const app = express()
const SECRET = process.env.FORMY_WEBHOOK_SECRET
const TOLERANCE_SECONDS = 300

// express.raw keeps the exact bytes Formy signed.
app.post('/hooks/formy', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-Formy-Signature') || ''
  const parts = Object.fromEntries(header.split(',').map((part) => part.split('=', 2)))
  const timestamp = Number(parts.t)
  if (!SECRET || !parts.v1 || !Number.isInteger(timestamp)) return res.status(401).send('Missing signature')
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return res.status(401).send('Stale signature')

  const expected = crypto.createHmac('sha256', SECRET).update(`${timestamp}.`).update(req.body).digest('hex')
  const received = Buffer.from(parts.v1)
  const wanted = Buffer.from(expected)
  if (received.length !== wanted.length || !crypto.timingSafeEqual(received, wanted)) {
    return res.status(401).send('Invalid signature')
  }

  const delivery = req.get('X-Formy-Delivery') // skip it if you have processed it before
  const event = req.get('X-Formy-Event')
  const payload = JSON.parse(req.body.toString('utf8'))
  console.log(event, delivery, payload.submission_id)
  res.sendStatus(200)
})

app.listen(3000)

import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ['FORMY_WEBHOOK_SECRET'].encode()

@app.post('/hooks/formy')
def formy_webhook():
    parts = dict(p.split('=', 1) for p in request.headers.get('X-Formy-Signature', '').split(',') if '=' in p)
    try:
        timestamp, received = int(parts['t']), parts['v1']
    except (KeyError, ValueError):
        abort(401)
    if abs(time.time() - timestamp) > 300:
        abort(401)
    raw = request.get_data()  # the exact bytes Formy signed
    expected = hmac.new(SECRET, f'{timestamp}.'.encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(received, expected):
        abort(401)
    payload = request.get_json()
    # skip request.headers['X-Formy-Delivery'] if you have processed it before
    return '', 200

<?php
// Laravel route; any PHP framework works the same way.
Route::post('/hooks/formy', function (Illuminate\Http\Request $request) {
    $secret = env('FORMY_WEBHOOK_SECRET');
    parse_str(str_replace(',', '&', (string) $request->header('X-Formy-Signature')), $parts);
    $timestamp = (int) ($parts['t'] ?? 0);
    $received = (string) ($parts['v1'] ?? '');
    if (! $secret || $received === '' || abs(time() - $timestamp) > 300) {
        abort(401);
    }
    // getContent() is the raw body, exactly as Formy signed it.
    $expected = hash_hmac('sha256', $timestamp.'.'.$request->getContent(), $secret);
    if (! hash_equals($expected, $received)) {
        abort(401);
    }
    $payload = $request->json()->all();
    // skip $request->header('X-Formy-Delivery') if you have processed it before
    return response()->noContent();
});

Test vector

Check your code against these values before you deploy it. With the secret below, this timestamp and this exact body, your code must produce this v1:

secret:    formy-docs-test-secret
t:         1760000000
body:      {"form_id":1,"form_slug":"service-agreement","submission_id":42}
v1:        a19954cefa0c3d8905f15db9c8ad77e85b8a338fad114a86761f8ce802c3ef68
legacy:    sha256=12ccf2f4ef7f8d199692cd842bac9c42d1300d33135e0d08cbb314e35cde7e56

printf '%s' '1760000000.{"form_id":1,"form_slug":"service-agreement","submission_id":42}' \
  | openssl dgst -sha256 -hmac 'formy-docs-test-secret' -hex

X-Webhook-Signature is the original scheme, kept for receivers built on it: an HMAC-SHA256 of the body alone, prefixed with sha256=. It has no timestamp, so it cannot stop a replay. Use X-Formy-Signature in new code.

Answer with a 2xx within 10 seconds. Formy does not follow redirects and counts a 3xx as delivered, which is how Google Apps Script web apps answer.

Attempts are made at the first try and then 30 seconds, 2 minutes, 10 minutes, 1 hour, 4 hours, 12 hours, 24 hours after it, 8 in all. Each wait can run up to a tenth longer, so the retries piled up during an outage do not all arrive in the same second.

• Every attempt is built when it is sent: a change to the URL, secret or headers applies to the retries still waiting, and a response deleted in the meantime is not sent.
• Pausing or deleting the webhook cancels the retries still waiting.
• When the last attempt fails, the form's owner gets one email. To keep a broken endpoint from flooding the inbox, Formy sends at most one such email per webhook a day for each cause, such as a 404 or an unreachable host.
• The response itself is always saved in Formy. Every attempt's outcome is under אירועים קודמים, and GET /open/forms/{form}/integrations/{integration}/events returns the same history.

[
  {
    "id": 1,
    "date": "2026-10-17 05:37",
    "created_at": "2026-10-17T05:37:41.000000Z",
    "status": "success",
    "data": { "delivery_id": "4fe482e4-56d7-4ef8-ab59-898acb70a211", "attempts": 1 }
  }
]

A delivery can reach you more than once, for example when your server processes it but answers after the 10-second limit and Formy retries. Store each X-Formy-Delivery you have processed and skip one you have seen.

Retries also mean deliveries can arrive out of order: an edit can arrive before a retried creation of the same response. Key your own record on submission_id, and create or update it, rather than always adding a new one.

• The URL must start with https://. A plain http:// address is refused when you save.
• It must resolve only to public IP addresses. An address on a private network, or on your own machine, is refused. To test locally, expose your server through a tunnel that gives you a public HTTPS address.
• The secret is optional and at least 12 characters long. Use a long random one.
• You can add up to 10 custom headers, each name and value up to 255 characters. To pass a token to your server, use a header of your own, such as X-Api-Key.

Formy refuses custom headers it sets itself or that could mislead your server:

Authorization
X-Webhook-Signature
X-Formy-Signature
X-Formy-Event
X-Formy-Delivery
Content-Type
Content-Length
Host
Cookie
X-CSRF-Token
X-Forwarded-For
X-Forwarded-Proto
X-Real-IP
X-Requested-With
Accept-Encoding
Transfer-Encoding

The Make card, and the cards for n8n, Activepieces, Pabbly and Albato, post the same payload without submission and message, but they are not webhooks in the sense of this page: they carry no signature headers, make one attempt with the same 10-second timeout, and do not retry. If you need signing and retries, point a התראת Webhook at the platform's incoming-webhook URL instead. See Automation endpoints.