DocsWebhooks
Webhooks
Deliver every response to your own backend: configure a webhook per form, verify its signature, and handle at-least-once retries.
Configure
Configure webhooks per form under Form settings → Webhooks. The signing secret is shown once, when the webhook is created. Each response POSTs JSON with these headers:
| Header | Value |
|---|---|
| Content-Type | application/json |
| X-Fillo-Event | response.created (the only event today) |
| X-Fillo-Signature | Hex HMAC-SHA256 of the raw request body, keyed with your signing secret |
| X-Fillo-Delivery-Id | Stable across retries of the same delivery — receivers can dedupe on it |
Payload
The payload carries the same data twice: flat Zapier-style keys at the top level, and a nested form + response shape — use whichever reads better.
{
"event": "response.created",
"id": "wA3kR9tL0qBn",
"response_id": "wA3kR9tL0qBn",
"submitted_at": "2026-07-04T09:41:23.512Z",
"form_id": "Jf2mX8pQ4sDv",
"form_name": "Conversion failed",
"form_slug": "conversion-failed",
"form_url": "https://fillo.so/f/conversion-failed",
"source": "app.example.com/convert",
"duration_ms": 8200,
"answers": {
"reason": "crash",
"details": "Export hung at 90%",
"email": "ada@example.com"
},
"formatted": {
"reason": "It crashed",
"details": "Export hung at 90%",
"email": "ada@example.com"
},
"fields": [
{ "id": "reason", "label": "What went wrong?", "kind": "select",
"value": "crash", "formatted": "It crashed" },
{ "id": "details", "label": "Tell us more", "kind": "long_text",
"value": "Export hung at 90%", "formatted": "Export hung at 90%" },
{ "id": "email", "label": "Email me when it's fixed", "kind": "email",
"value": "ada@example.com", "formatted": "ada@example.com" }
],
"files": [],
"meta": { "source": "app.example.com/convert", "duration_ms": 8200 },
/* Same data again, nested — "form": { id, slug, name }, "response": { id, data,
answers, formatted, fields, files, meta, createdAt }. Use whichever shape reads better. */
"form": { … },
"response": { … }
}answers is keyed by field id with raw values; formatted holds display strings (option labels, not ids). File uploads appear in files with name, size, mime, and a download url that requires a signed-in workspace member.
Verify the signature
Verify the signature against the raw bytes before trusting a request:
import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";
const app = express();
// Verify against the RAW request bytes — parsing and re-stringifying changes them.
app.post("/hooks/fillo", express.raw({ type: "application/json" }), (req, res) => {
const expected = createHmac("sha256", process.env.FILLO_WEBHOOK_SECRET)
.update(req.body) // Buffer of the raw body
.digest("hex");
const given = req.get("X-Fillo-Signature") ?? "";
const ok =
given.length === expected.length &&
timingSafeEqual(Buffer.from(given), Buffer.from(expected));
if (!ok) return res.status(401).end();
const event = JSON.parse(req.body.toString("utf8"));
// Deliveries are at-least-once — key your side effects on event.response.id.
console.log("new response", event.response.id);
res.status(200).end();
});Delivery and retries
The first attempt fires immediately after the response is stored. A non-2xx status or a 10-second timeout counts as a failure; failed deliveries retry with backoff — about 1 minute, 5 minutes, 30 minutes, 2 hours, then 6 hours — up to 6 attempts total. Requests never follow redirects, and production deliveries are HTTPS-only.
Deliveries are at-least-once
A retry can arrive after your server already processed a request whose acknowledgment was lost, so key your side effects on the response id.