Webhook Payload & Signature Reference

Every FluoTest webhook integration sends an HTTP POST with a JSON body when a quiz is submitted. This page documents the request format, the default payload fields, the alternate payload shape used with field mapping, and the signature scheme.

Last updated July 10, 2026

What does a FluoTest webhook payload look like?

By default it's a flat JSON object with the submission's identifiers, contact fields, score, tier or outcome, the full answers object, and a submission timestamp. If a signing secret is set, requests include an X-FluoTest-Signature header (HMAC-SHA256 of the raw body).

Configuration

A webhook integration is configured with a destination URL and an optional signing secret. No OAuth or third-party account connection is required.

Request format

Every webhook request is sent with the following method and headers:

Header	Value	Notes
Method	POST	Always a POST request.
Content-Type	application/json	The body is JSON-encoded.
User-Agent	FluoTest-Webhook/1.0	Identifies the request as coming from FluoTest.
X-FluoTest-Event	submission.created	The only event type currently sent.
X-FluoTest-Signature	sha256=<hex>	Present only when a signing secret is configured for the webhook.

Default payload fields

Without field mapping configured, the request body is a flat JSON object:

{
  "submission_id": "8f2b1c3a-...",
  "test_id": "3a9d7e10-...",
  "test_name": "Lead Fit Quiz",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "company": "Acme Inc",
  "contact_type": "email",
  "respondent_name": "Jane Doe",
  "total_score": 82,
  "max_score": 100,
  "score_percent": 82,
  "tier": "High fit",
  "scores": null,
  "outcome": null,
  "outcomes": null,
  "disqualified": false,
  "answers": {
    "sections": [
      {
        "section_title": "Section 1",
        "questions": [
          {
            "question_id": "q1",
            "question_text": "What's your role?",
            "question_type": "multiple_choice",
            "answer": "Founder"
          }
        ]
      }
    ]
  },
  "submitted_at": "2026-07-10T14:32:00.000Z"
}

Field	Type	Description
submission_id	string	Unique ID of the submission.
test_id	string	ID of the quiz.
test_name	string	Name of the quiz.
email	string \| null	Respondent's email, if collected.
first_name	string \| null	Respondent's first name, if collected.
last_name	string \| null	Respondent's last name, if collected.
company	string \| null	Company name, if collected.
contact_type	string \| null	Which contact method was collected: "email", "phone", or null.
respondent_name	string \| null	Full name, if a name question was answered.
total_score	number	The respondent's total score.
max_score	number	The maximum possible score.
score_percent	number	Score expressed as a percentage.
tier	string \| null	Label of the matched score tier (single-score quizzes).
scores	object \| null	Per-category scores for multi-score quizzes; null otherwise.
outcome	string \| null	Key of the matched primary outcome (Pro outcome engine only).
outcomes	string[] \| null	Keys of all matched outcomes.
disqualified	boolean	Whether the respondent was disqualified.
answers	object	Nested sections/questions/answers — see below.
submitted_at	string	ISO 8601 submission timestamp.

Sending a subset of fields

A webhook can be configured to send only a chosen subset of the fields above. submission_id and test_id are always included regardless of that selection, so every payload can be traced back to its source.

Mapped payload mode

When field mapping is configured for a webhook (see Field Mapping & Sync Retries), the payload shape changes: the mapped fields produced by the mapping rules replace the flat structure, alongside any tags, and the full default payload is included unmodified under raw.

{
  "mapped": { "email": "[email protected]", "score": 82 },
  "tags": ["High fit"],
  "raw": { "submission_id": "8f2b1c3a-...", "...": "..." }
}

Verifying the signature

When a signing secret is set, every request includes an X-FluoTest-Signature header: the HMAC-SHA256 hex digest of the exact request body, computed with the shared secret and prefixed with sha256=. Recompute the same digest over the raw request body on the receiving end and compare it to the header to confirm the request came from FluoTest and wasn't altered in transit.

const crypto = require("crypto");

function isValidSignature(rawBody, header, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return header === expected;
}

Delivery, retries, and failures

A webhook request times out after 10 seconds. A non-2xx response status is treated as a failed delivery. Failed deliveries are retried automatically — see Field Mapping & Sync Retries for the retry schedule and how failures are logged.

Frequently asked questions

What triggers a FluoTest webhook?

A webhook fires once per quiz submission, with the event type submission.created. There is currently no other event type.

How do I verify the X-FluoTest-Signature header?

Compute an HMAC-SHA256 digest of the raw request body using the signing secret configured for the webhook, hex-encode it, prefix it with sha256=, and compare it to the header value using a constant-time comparison.

What happens if my endpoint is unreachable or returns an error?

The delivery is marked failed and retried automatically with backoff, up to 3 additional attempts, unless the failure is considered permanent.

Can I choose which fields are sent in the payload?

Yes. A webhook can be configured with a specific list of fields; only those fields, plus submission_id and test_id, are included in each request.