Webhooks reference

Headers, payload fields and signature verification for Finerlise webhooks.

Set up a webhook from a form’s Integrations page. See Webhooks.

Request

Method	`POST`
Content type	`application/json`
Timeout	10 seconds. Reply with any `2xx` status.
Retries	None. Use the API to fetch anything you missed.

Headers

Header	Value
`X-Finerlise-Event`	`response.completed`
`X-Finerlise-Delivery`	A unique ID for this delivery. Use it to ignore duplicates.
`X-Finerlise-Signature`	`sha256=<hex>`, only when you set a signing secret.

Payload

eventstring

Always response.completed.

createdAtstring

When the event was sent (ISO 8601).

data.formIdstring

The form’s ID.

data.formTitlestring

The form’s title.

data.responseIdstring

The response’s ID. Use it with GET /api/v1/responses/{responseId}.

data.respondentEmailstring | null

The respondent’s email, when the form identifies respondents.

data.completedAtstring

When the response was submitted (ISO 8601).

data.answersarray

One item per answer: fieldId, label, type, value (formatted text) and rawValue.

data.fieldsobject

Answers keyed by question title, for quick access.

data.hiddenFieldsobject

Hidden field values from the form link.

data.metadataobject

Extra response metadata.

Verify the signature

The signature is an HMAC-SHA256 of the raw request body using your signing secret. Compute it yourself and compare in constant time.

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/finerlise",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const expected =
      "sha256=" +
      crypto
        .createHmac("sha256", process.env.FINERLISE_WEBHOOK_SECRET)
        .update(req.body)
        .digest("hex");
    const received = req.get("X-Finerlise-Signature") ?? "";

    const valid =
      expected.length === received.length &&
      crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
    if (!valid) return res.sendStatus(401);

    const event = JSON.parse(req.body.toString("utf8"));
    console.log("New response", event.data.responseId);
    res.sendStatus(200);
  }
);

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

app = Flask(__name__)

@app.post("/finerlise")
def finerlise():
    secret = os.environ["FINERLISE_WEBHOOK_SECRET"].encode()
    expected = "sha256=" + hmac.new(secret, request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Finerlise-Signature", "")):
        abort(401)
    event = request.get_json()
    print("New response", event["data"]["responseId"])
    return "", 200