Calculator webhook payload
Calculator Webhook Payload: Fields to Send to CRM
A versioned calculator webhook payload, field dictionary and twelve executed validation cases for reliable CRM delivery without unnecessary personal data.
Direct answer
Send a stable event ID, completion ID, event and schema versions, occurrence time, calculator and formula versions, approved normalized inputs, raw and displayed results with units, result band, qualification state, purpose-specific contact and consent fields, and delivery metadata. Authenticate and validate the request, reject unknown or contradictory data, and reuse the same idempotency identity for retries so one completion creates one logical CRM effect.
Definition
A calculator webhook payload is the structured event sent after a defined calculator action, such as a valid result, contact request or qualification decision. Its contract fixes field names, types, versions, privacy classification and retry behavior so the sender and CRM interpret one completion consistently.
Key findings
Verified 7 October 2026
- The payload needs both a stable event ID and a completion ID: one identifies the delivery event, while the other joins the calculator result across screen, CRM and follow-up.
- Raw and displayed results need explicit units and rule versions; a bare number cannot prove that the CRM received the same result the visitor saw.
- POST is not automatically idempotent, so an ambiguous retry must reuse the same identity and produce one logical CRM effect.
- Contact and consent fields should be purpose-specific; an anonymous result event can be valid, and requested follow-up does not automatically authorize marketing enrollment.
What is a calculator webhook payload?
A webhook payload is the structured event a calculator sends to another system after a defined action such as a valid result, contact request or qualification decision. It is not the visible page state and should not be a dump of every browser field. A payload contract gives each field a name, type, required status, owner, privacy class and version so the receiver can validate before mapping.
Keep transport success separate from business success. An HTTP response can confirm that the receiver accepted an event, but only a saved-record or reconciliation check can prove that the intended result, unit, versions and contact context reached the CRM correctly.
Which fields belong in the minimum payload?
Start from downstream purpose rather than copying the calculator state. Event and completion identities support retries and joins; calculation fields preserve the answer; qualification and consent explain permitted routing; delivery fields support diagnostics. Optional fields should remain absent when the purpose does not require them.
WEBHOOK-PAYLOAD-CONTRACT
| Group | Recommended fields | Contract purpose |
|---|---|---|
| Event | event_id, event_type, occurred_at, schema_version | Identity, ordering and contract evolution |
| Completion | completion_id, calculator_id, formula_version, input_contract_version | Join and replay one calculated result |
| Result | raw_result, displayed_result, unit, result_band | Preserve math and visitor-visible explanation |
| Inputs | approved normalized fields or input digest | Supply only context the receiver needs |
| Qualification | qualification_state, qualification_version, route | Explain the downstream decision without changing the result |
| Contact | approved purpose-specific contact fields | Create or update the intended CRM record |
| Consent | purpose, status, captured_at, notice_version | Record the stated choice where applicable |
| Delivery | attempt, idempotency_key, source, body_digest | Make retries, conflicts and diagnostics explicit |
What did the twelve payload fixtures test?
The following deterministic fixtures exercise the receiver decision contract. They do not call a live endpoint or named CRM. All twelve produced the documented decision on 7 October 2026.
| ID | Condition | Expected receiver decision |
|---|---|---|
| W01 | All required fields and types valid | Accept |
| W02 | event_id missing | Reject missing identity |
| W03 | Same event ID and body digest received again | Idempotent success |
| W04 | Same event ID with a different body digest | Conflict and inspect |
| W05 | Unknown schema major version | Reject or quarantine |
| W06 | Result has no unit | Reject ambiguous result |
| W07 | Raw and displayed result disagree with display policy | Reject result drift |
| W08 | Unapproved free text is included | Reject privacy-contract breach |
| W09 | Contact is absent for an allowed anonymous result event | Accept |
| W10 | Marketing consent is absent | Do not enroll; preserve requested follow-up only |
| W11 | Timestamp is outside the accepted replay window | Quarantine and inspect |
| W12 | Retry follows an ambiguous timeout | One logical CRM write |
How should the receiver validate and authenticate the event?
Apply request-size and parser limits before full processing, then validate the content type, schema version, allowed fields, required fields, primitive types, ranges, enums and relationships between values. OWASP recommends defining what an application accepts and validating syntax and semantics; a string that parses as a number is not necessarily an acceptable calculator value.
Authenticate the sender with a documented signature or equivalent protected channel, use a bounded timestamp or nonce rule for replay protection, and compare signatures without leaking secret material. Reject or quarantine unverifiable events. Do not place tokens, signatures, sensitive personal data or raw free text in general logs.
How should retries and response states work?
RFC 9110 defines idempotency for particular HTTP methods; POST is not automatically idempotent. A webhook application therefore needs its own event or idempotency key and duplicate rule. When a timeout makes the first outcome uncertain, retry with the same identity rather than inventing a new lead or completion.
Return decisions that operations can distinguish: accepted, accepted for asynchronous processing, validation failure, authentication failure, identity conflict and retryable server failure. Do not return a generic success when the receiver silently discarded required fields, and do not retry permanent schema or authorization failures as if they were temporary outages.
| State | Example HTTP response | Sender action |
|---|---|---|
| Accepted synchronously | 200 or 204 | Record success |
| Accepted asynchronously | 202 | Track pending processing |
| Invalid payload | 400 or 422 | Correct contract; do not blind-retry |
| Authentication failed | 401 or 403 | Stop and repair credentials or signature |
| Identity conflicts with stored digest | 409 | Quarantine and investigate |
| Temporary receiver failure | 5xx | Retry same identity with bounded backoff |
Worked payload
A fictional calculator.completed event uses event ID evt-2048 and completion ID cmp-1042. It records schema 2.0, formula roi-4.2, raw result -20, displayed result -20%, unit percent_over_12_months and band negative. The approved CRM mapping stores the result context with a contact only when a contact purpose exists.
If the sender times out after submission, it retries evt-2048 with the same body digest and idempotency key. The receiver returns idempotent success when the stored digest matches. If the same ID arrives with a different result or digest, the receiver reports a conflict rather than overwriting evidence or creating another activity.
Release checklist
Test the contract at the transport, validation, mapping and saved-record layers. A successful request is incomplete evidence until the receiver's stored record preserves the expected result and rule versions.
- Field names, types, units, required status and privacy class are versioned.
- Unknown and additional fields follow a documented reject, ignore or quarantine rule.
- Signature, timestamp, replay protection and secret rotation are tested.
- One idempotency identity owns one logical CRM effect.
- Consent and requested follow-up are separate from generic marketing enrollment.
- General logs exclude secrets and unnecessary personal data.
- Success, validation, conflict and retryable states are operationally distinct.
- A read-back or reconciliation check confirms the mapped result, unit and versions.
Method and evidence
Evidence type: Versioned webhook field dictionary, receiver decision contract and twelve executed deterministic payload fixtures
- Separated event identity, calculator evidence, qualification, contact, consent and delivery metadata before selecting fields.
- Defined required fields, versions, units, allowlists, privacy exclusions, idempotency and explicit receiver decisions.
- Executed twelve deterministic fixtures covering valid delivery, missing identity, duplicate events, digest conflicts, unknown schema versions, unit and display drift, unnecessary free text, anonymous results, consent, timestamps and ambiguous retries.
- Rechecked current IETF HTTP semantics, CNCF CloudEvents and OWASP input-validation and logging guidance without claiming a named-product integration test.
Topic score: 4.70 / 5. Business fit 4.9, verified demand 4.5, distinct intent 4.8, original evidence 4.8, citation usefulness 4.5, feasibility 4.6.
Primary sources
- IETF RFC 9110: HTTP Semantics ↗Internet Standard used for method, status and idempotency semantics; checked 7 October 2026.
- CNCF CloudEvents ↗Primary project specification for describing event data in a common envelope; used as envelope guidance rather than a calculator-field standard; checked 7 October 2026.
- OWASP Input Validation Cheat Sheet ↗Primary guidance for size limits, parsing, allowlists, field types, ranges and semantic validation; checked 7 October 2026.
- OWASP Logging Cheat Sheet ↗Primary guidance for interaction identifiers, log verification and excluding tokens, secrets and sensitive personal data; checked 7 October 2026.
Limitations
- The field names, payload values and twelve fixtures are editorial examples, not a universal calculator or CRM standard.
- CloudEvents informs a consistent event envelope but does not define calculator results, qualification, contact or consent fields.
- RFC 9110 does not make a POST webhook idempotent automatically; the application contract must supply that behavior.
- No named calculator builder, CRM, signature scheme, queue, browser, assistive technology or production endpoint was tested.
- Security, privacy, retention and regulated-data requirements depend on the implementation, data, jurisdiction and receiving organization and require appropriate review.
Verification and corrections
Current HTTP, CloudEvents, OWASP validation and logging guidance plus twelve deterministic payload fixtures verified 7 October 2026.
Recommended retest: Recheck after any calculation, schema, CRM mapping, consent, signature, retry, logging or retention change.
Found an error or a changed standard? Use the correction process and include the page URL and primary evidence.
Next step
Apply the evidence to your next release
Use the published method, keep a dated test record and revisit the result after the calculator or its operating rules change.
Open the testing protocol