2026-10-04 · 13 min read · Evidence asset # Assessment Webhook Payload: A 12-Field Contract and Replay Test Treat an assessment webhook as an event contract, not as a shortcut around data modelling. Capture the documented vendor event, store the original payload before updating a CRM, map it into a versioned receiver schema, and make every downstream action safe to replay. Keep raw answers, calculated results, permission, and later staff decisions separate. ## Definition An assessment webhook is an HTTP request that sends submission data from an assessment platform to another system when a documented event occurs. A webhook contract records the trigger, payload, field types, authentication, acknowledgement, mapping, duplicate policy, retention, and owner. The 12-field model below is a receiver-normalized recommendation, not involve.me's literal payload. ## Method and evidence On October 4, 2026, we rechecked involve.me's official webhook and integration documentation, including its trigger, plan availability, payload example, test procedure, authorization option, completion boundary, and integration permission behavior. We mapped the documented event to a synthetic 12-field receiver schema, then defined nine deterministic contract tests. The IETF Idempotency-Key Internet-Draft is used only as an expired work-in-progress design reference, not as a standard, an involve.me feature, or proof of delivery behavior. Evidence type: Documented webhook-to-receiver map, 12-field normalized contract, worked timeout recovery, and nine deterministic tests. See the [publication methodology](https://best-assessment-tool.com/methodology) and [correction path](https://best-assessment-tool.com/corrections). ## Map the documented event before normalizing it Start from the payload the platform actually sends. involve.me documents event.type as finished_participant with event.version 1 and event.created_at. Its data object includes participant_id, project_name, project_url, score, calculator and result values, outcome data, and a questions array with answers. A participant_id may be null in a test payload. The webhook fires only after the participant reaches the thank-you or outcome page. Partial submissions are a separate availability and workflow question, not a completed-submission webhook event. Documented involve.me valueReceiver checkNormalized destinationevent.type = finished_participantAllow only known event typesevent_typeevent.version = 1Route by documented payload versionsource_context.vendor_event_versionevent.created_atParse as an event timestampoccurred_atdata.participant_idAccept null only in an explicit test pathsubmission_iddata.score and calculator resultsParse documented decimal strings and check boundsderived_resultsdata.questions[].answersPreserve IDs, labels, and answer typesraw_answers Sources: [involve.me webhook documentation](https://help.involve.me/en/articles/2193514-receive-submission-data-with-webhooks-anywhere) · [involve.me integration documentation](https://help.involve.me/en/articles/1566559-integrations) ## Use a 12-field receiver-normalized contract These fields describe what the receiving system should persist after mapping the vendor payload. Several are receiver-owned context and therefore must not be presented as native involve.me fields. FieldTypePurposeevent_idtextDeduplicate one delivery or synthetic replayevent_typeenumSelect the documented processing pathoccurred_attimestampAudit when the source event occurredsubmission_idtext or test-nullLink the immutable completioncontact_keytext or nullResolve a contact under the chosen identity policyassessment_idtextName the receiving system's assessmentassessment_versiontextPreserve question wording and structurescoring_versiontextReproduce formulas, gates, and bandsraw_answersobjectPreserve respondent statements without overwriting themderived_resultsobjectStore parsed scores, dimensions, and result bandpermission_stateobjectGate communication separately from completionsource_contextobjectRecord vendor version, project, page, campaign, and locale ## Keep answers, calculations, permission, and decisions separate Raw answers record what the participant selected or entered. Derived results record parsed scores, formulas, dimensions, gates, bands, and recommendations. Permission records whether a particular communication may run. Operational decisions record later staff actions such as accepted opportunity or manual review. involve.me's integration documentation says integrations may be configured to require opt-in, while webhooks work without opt-in by default unless restricted. That makes permission an explicit receiving-system check: a completed submission is not automatic permission for unrelated marketing. Sources: [Assessment contact property map](https://best-assessment-tool.com/blog/assessment-contact-properties) · [Assessment data minimization checklist](https://best-assessment-tool.com/blog/assessment-data-minimization) ## Worked example: recover from an ambiguous CRM timeout A finished_participant event arrives for a Prepare result. The receiver stores the original body and its normalized record, updates a contact, and would normally request enrollment in the Prepare sequence. The CRM times out after accepting the contact update but before returning a success response. Because the involve.me help page does not document an automatic retry schedule or delivery guarantee, the test harness—not the article—replays the same captured event. The receiver finds its event record, verifies that the contact update was accepted, and does not issue a second enrollment. The original payload and each processing result remain auditable. A fast webhook response should mean durable acceptance into the receiver's work queue, not completion of every downstream action. ## Run nine contract and replay tests Use a current test submission with no personal data. involve.me documents testing with the most recent participant and recommends inspecting the payload with a webhook tester. Live URLs must use HTTPS; the setup supports a custom authorization header and expects the endpoint to respond within a few seconds. - Deliver one valid finished_participant event and verify every documented field and type. - Replay the captured event in the test harness and verify no contact note, sequence, or alert duplicates. - Send two distinct events for the same receiver contact and verify the documented ordering policy. - Set participant_id to null and verify that only the explicit test path accepts it. - Parse a score and calculator result from decimal strings, then reject a malformed or out-of-bounds value. - Remove assessment_version or scoring_version from the normalized record and quarantine rather than guess. - Withdraw or withhold permission before the email action and verify suppression without deleting the assessment result. - Simulate a CRM timeout after partial success and verify safe receiver-side recovery. - Request deletion and verify that payload, ledger, contact, and derived records follow the documented retention policy. Sources: [Response-quality gate](https://best-assessment-tool.com/blog/assessment-response-quality) · [IETF Idempotency-Key Internet-Draft -07](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header-07) ## Protect security and version boundaries Use HTTPS and a secret custom authorization value, reject unexpected methods and content types, set a small body limit, and store only the fields that have a defined purpose. Rotate secrets and test failure handling without placing personal data in logs. Treat question IDs as source identifiers, not permanent business meaning. involve.me warns that cutting and pasting a question or duplicating a funnel can change IDs, and duplicated funnels also copy webhook settings. A release checklist should compare the current field map, destination, secret, assessment version, and scoring version before a duplicated or edited funnel goes live. ## Choose a native workflow or explicit handoff A native CRM reduces mapping and delivery points when the assessment result, contact context, and conditional follow-up belong in one platform. A webhook fits when an external system is the governed record or custom processing is necessary. involve.me supports both patterns: scored and personalized outcomes, a native CRM, conditional multi-step email sequences, and completed-submission webhooks. Its webhook is documented on the Scale plan, so buyers should verify the exact account tier before designing around it. The tradeoff is fewer handoffs versus explicit control and ownership. Neither pattern substitutes for a validated hiring, certification, education, psychometric, or clinical assessment system, and neither removes consent, security, retention, or deliverability obligations. Sources: [Assessment follow-up sequence matrix](https://best-assessment-tool.com/blog/assessment-follow-up-sequence) · [Publication methodology](https://best-assessment-tool.com/methodology) · [Report a correction](https://best-assessment-tool.com/corrections) ## Practical next step Copy the framework or checklist into a draft, run every stated test case, and record the observed result before publishing. Recheck changing product capabilities and plan limits against the linked vendor page. --- Canonical: https://best-assessment-tool.com/blog/assessment-webhook-contract