Webhooks
A webhook sends every new submission of a survey to an address of your choice, as a signed HTTPS request with the answers as JSON. Use it to pass submissions on to your own server, or to Zapier, Make or n8n.
Set up a webhook
- Open a survey and go to the “Integrations” tab.
- Under “Webhooks”, click “Add webhook”, give it a name and enter the address of your endpoint.
- Click “Send test” to send a sample submission, marked with
"test": true.
A webhook belongs to the workspace and can be used by several of its surveys; each survey switches it on for itself. Editors and admins can add, change and test webhooks. Each delivery uses 1 credit; tests are free.
The address has to fulfil a few rules, which protect you and us:
- https on the default port (443), under a domain name. IP addresses and internal names are not accepted.
- No user name or password in the address.
- Redirects are not followed: enter the final address.
The request
Floxity sends a POST request with a JSON body and these headers, which follow the open Standard Webhooks specification:
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Floxity-Webhooks/1 (+https://floxity.com/developers/webhooks)
webhook-id: msg_2f6a1c0e9b7d4a53b1c8e0f4a6d2c9b7
webhook-timestamp: 1794751200
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=webhook-id: the id of the message. It stays the same for every attempt and for every resend of the same submission to the same webhook.webhook-timestamp: when this attempt was sent, in seconds since 1970 (UTC).webhook-signature: the signature of this attempt, see Verify the signature.
The payload
There is one event, form.submitted, in version v1. New optional fields may be added to v1 at any time, so ignore fields you don’t know. Anything incompatible would come as a new version.
{
"id": "msg_2f6a1c0e9b7d4a53b1c8e0f4a6d2c9b7",
"type": "form.submitted",
"version": "v1",
"test": false,
"createdAt": "2026-11-15T14:00:00.000Z",
"form": {
"id": "5f0c2f6e-58a1-4a39-9f0b-0d7d6f1f2a01",
"title": "Customer feedback"
},
"submission": {
"id": "0b0e7a52-6a0e-4b6e-9d2f-3f1f6c1f7a11",
"submittedAt": "2026-11-15T13:59:58.120Z",
"url": "https://floxity.com/app/surveys/5f0c2f6e-…/results/responses?submission=0b0e7a52-…"
},
"answers": {
"b29b1f53-49a6-411a-9ee4-384c825891d9": {
"title": "Your name",
"type": "short_text",
"value": "Ada"
},
"307662f8-e0d7-47dc-8b1a-7ff882460217": {
"title": "How did you hear about us?",
"type": "single_choice",
"value": "Other",
"other": "A podcast"
},
"9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f": {
"title": "Rate us",
"type": "rating",
"value": 4,
"max": 5
},
"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d": {
"title": "Phone",
"type": "phone",
"value": null
}
},
"hiddenFields": {
"utm_source": "newsletter"
}
}id: the same value as the headerwebhook-id.test:truefor “Send test”, which uses sample answers and a submission that doesn’t exist.form.idandsubmission.id: stable ids of the survey and the submission.submission.url: the submission in Floxity. Opening it needs a login with access to the survey.answers: every question of the survey by its id, in the order of the survey. The id of a question never changes, also when its title does. A question that wasn’t answered or wasn’t shown has the valuenull. Texts between the questions are not included.hiddenFields: the hidden fields that were filled, by the name of their URL parameter.
The value of an answer depends on the type of the question:
| type | value |
|---|---|
| short_text, long_text, email, phone, website | String |
| number | Number |
| rating | Number, with max: the highest rating possible |
| nps | Number from 0 to 10, with comment if a reason was given |
| single_choice, dropdown | String: the text of the chosen option. With other: the text typed for “Other” |
| multiple_choice | Array of strings, with other as above |
| yes_no | Boolean |
| consent | true |
| date | String: an ISO date (2026-12-24). With a time: the moment in UTC, with timeZone: the respondent’s time zone |
The payload never contains anything about the respondent’s device (IP address, browser) and nothing about your account. A payload larger than 1 MB is not sent.
Verify the signature
Anyone who knows the address of your endpoint can send requests to it. The signature shows that a request comes from Floxity and was not changed on the way. Every webhook has its own signing secret, which starts with whsec_: open the webhook in the “Integrations” tab and use “Reveal” or “Copy”. Keep it on your server only.
The signature is an HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{body} with the secret (the part after whsec_, base64 decoded) as key, base64 encoded and prefixed with v1,. Three things matter:
- Use the body exactly as it arrived, before parsing it. A parsed and re-serialized body gives another signature.
- Compare in constant time, with the function your language offers for it.
- Refuse requests whose timestamp is more than 5 minutes off, so a recorded request can’t be sent again later.
Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';
// rawBody: the body exactly as received (a string), before any JSON parsing
// headers: the request headers with lower-case names
// secret: the signing secret of the webhook (whsec_…)
export function verifyFloxityWebhook(rawBody, headers, secret) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const signatures = headers['webhook-signature'] ?? '';
if (!id || !timestamp) return false;
// Refuse requests older than 5 minutes (replays)
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key)
.update(id + '.' + timestamp + '.' + rawBody)
.digest();
// Several signatures while a secret is rotated: one of them has to match
return signatures.split(' ').some((part) => {
const [version, value] = part.split(',');
const given = Buffer.from(value ?? '', 'base64');
return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected);
});
}Python
import base64
import hashlib
import hmac
import time
def verify_floxity_webhook(raw_body: bytes, headers: dict, secret: str) -> bool:
"""raw_body: the body exactly as received, before any JSON parsing.
headers: the request headers with lower-case names.
secret: the signing secret of the webhook (whsec_...)."""
msg_id = headers.get("webhook-id", "")
timestamp = headers.get("webhook-timestamp", "")
signatures = headers.get("webhook-signature", "")
if not msg_id or not timestamp.isdigit():
return False
# Refuse requests older than 5 minutes (replays)
if abs(time.time() - int(timestamp)) > 300:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = f"{msg_id}.{timestamp}.".encode() + raw_body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
# Several signatures while a secret is rotated: one of them has to match
return any(
part.startswith("v1,") and hmac.compare_digest(part[3:], expected)
for part in signatures.split(" ")
)Instead of your own code you can use one of the Standard Webhooks libraries, which exist for many languages and take the secret as it is.
Respond
- Answer with a status from 200 to 299 within 10 seconds. Every other status and a later answer count as failed.
- Answer first and do the work afterwards if it can take longer.
- What your server answers in the body is never read or stored.
Retries, failures and pausing
- A delivery that fails with a timeout, a connection error or the status 408, 425, 429 or 500 to 599 is tried once more after 5 minutes. Other statuses are final at once: a second attempt would get the same answer.
- A failed delivery is not sent again by itself afterwards. The submission stays in Floxity, where you can resend it.
- After 20 failed deliveries in a row the webhook is paused for all surveys that use it, and the admins and editors of the workspace get one email. The status 410 (Gone) pauses it at once.
- While paused, nothing is sent and no credits are used. “Resume” in the “Integrations” tab sends a test first and continues only if it goes through.
- The “Integrations” tab shows the last errors of a webhook with a link to each submission.
- A delivery uses its credit also when it fails on your side.
Duplicates and resending
Your endpoint may get the same message more than once: when it took the first attempt but answered too late, or when someone uses “Resend” in the view of a submission. Both come with the same webhook-id, so store the ids you have handled and skip the ones you know.
Rotate the signing secret
“Rotate” gives a webhook a new secret, which is valid at once. For 24 hours every request carries two signatures, separated by a space: one with the new secret and one with the old. Accept a request if one of them matches, as the examples above do, and switch your server to the new secret within that time.
Zapier, Make and n8n
These tools give you an address that takes the request and starts a workflow with it.
Zapier
- Create a Zap and choose “Webhooks by Zapier” as the trigger, with the event “Catch Hook”. This needs a paid Zapier plan.
- Copy the webhook URL Zapier shows and add it as a webhook in Floxity.
- Use “Send test” in Floxity while Zapier is waiting for a request, so it finds the fields of your survey.
Make
- Create a scenario and add the module “Webhooks” → “Custom webhook”.
- Click “Add”, give it a name, copy the address and add it as a webhook in Floxity.
- Use “Send test” in Floxity while Make is waiting for data, so it learns the fields.
n8n
- Add a “Webhook” node to your workflow and set “HTTP Method” to POST.
- Copy the “Production URL”, not the “Test URL”, and add it as a webhook in Floxity.
- Activate the workflow, then use “Send test” in Floxity. A self-hosted n8n has to be reachable under a domain with https.
These tools don’t check the signature by themselves. The address they give you is the only protection there, so treat it like a password.
For Slack there is an own integration in the same tab, which posts submissions as readable messages. A Slack address doesn’t work as a webhook.