Results-ready webhooks

This page describes the verified development sender. Live webhook availability must be agreed with WFA. Configure your own HTTPS receiver; a report link from create is not a webhook.

Enable delivery

Configure your company’s API Results Webhook URL in the Bubble development database. It must be an HTTPS URL without a username or password in the URL. An empty value disables delivery. This setting is managed by the WFA team; it is not a create-request parameter. Only API-created assessments trigger delivery. After the risk, solution and country-summary results are saved, the backend schedules the private api_results_ready workflow. A report URL returned by create is separate from this event.

Event

The event ID is stable for one assessment. WFA results include cumulativePeRiskLevel; HFA results include contractorMisclass instead. The result fields have the same values and types as the retrieve response.

{
  "eventId": "assessment.results_ready:YOUR_TEST_ASSESSMENT_ID",
  "type": "assessment.results_ready",
  "schemaVersion": 1,
  "environment": "development",
  "assessmentId": "YOUR_TEST_ASSESSMENT_ID",
  "companyId": 2208001,
  "data": {
    "assessmentId": "YOUR_TEST_ASSESSMENT_ID",
    "employeeId": "STAFF-001",
    "complianceTeamMemberId": "COMPLIANCE-001",
    "managerId": "",
    "workingRights": 7,
    "payrollTax": 2.4,
    "socialSecurity": 5.5,
    "corporateTax": 3,
    "employmentLaw": 4.3,
    "overallTrip": 4.6,
    "cumulativePeRiskLevel": "Medium"
  }
}

Verify the signature

This development implementation uses the company’s existing API token as its HMAC signing key. Keep it on your server. The sender never transmits the token in the callback body or Authorization header.

Header	Value
`X-WFA-Timestamp`	Delivery timestamp as Unix seconds.
`X-WFA-Signature`	`sha256=` followed by a lowercase HMAC-SHA256 hex digest.
`X-WFA-Event-Id`	Stable event ID.
`X-WFA-Delivery-Attempt`	Attempt number, starting at 1. Operational metadata.

The signed content is the timestamp, a literal period, then the exact UTF-8 request body. Do not parse and reserialize the body before verification. Reject timestamps more than five minutes from your server clock, then compare signatures in constant time. Validate the authenticated company and event schema before storing data. Compare X-WFA-Event-Id with the verified body’s eventId. The attempt header is operational metadata, not part of the signed content. Timestamp validation and the inbox event ID together prevent stale delivery and duplicate processing; a fresh retry uses a new timestamp and the same event ID/body.

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody is a Buffer captured before a JSON body parser runs.
const expected = Buffer.from('sha256=' + createHmac('sha256', process.env.WFA_COMPANY_TOKEN)
  .update(timestamp + '.')
  .update(rawBody)
  .digest('hex'));
const received = Buffer.from(signature || '');
const timestampValid = /^\d{10,11}$/.test(timestamp || '') &&
  Math.abs(Date.now() - Number(timestamp) * 1000) <= 300_000;
const valid = timestampValid && received.length === expected.length &&
  timingSafeEqual(received, expected);

Acknowledgement and retries

Persist a verified event before returning any 2xx response. Delivery is at least once: use a unique database key on company ID + event ID so repeated deliveries have one effect. Reject a reused event ID with different result data rather than silently replacing the original event. The development sender makes at most four attempts: immediately, then after 10 seconds, 30 seconds and 120 seconds following the preceding failed attempt. Each HTTP request has an eight-second timeout. Timeouts, connection failures, HTTP 408, 429 and 5xx responses retry. Other non-2xx responses stop delivery, including redirects. A disabled URL does not send anything. Each attempt is recorded in the private API Webhook Delivery type with company/assessment IDs and JSON diagnostics. Records distinguish delivered, retry, failed, exhausted and disabled. A retry reuses the first complete result snapshot, so intervening decision updates do not alter that callback’s data. Results that are still Pending are retried within the same bounded attempt limit. To replay an exhausted development delivery, a WFA administrator can schedule api_results_ready with the same assessment/company, attempt 1 and the previously recorded payload. Preserve the event ID. An invalid URL or signing configuration should be corrected before replay.

Polling fallback

If webhooks are disabled or a delivery is exhausted, use retrieve. A suggested development client policy is polling every five seconds for up to two minutes, then surfacing a processing state and allowing a later check. This is a client policy, not a processing-time SLA. Create and decision requests should not be automatically repeated with new identifiers after an uncertain timeout.

Getting started

API reference

Reference

Help

Results-ready webhooks

Enable delivery

Event

Verify the signature

Acknowledgement and retries

Polling fallback

​Enable delivery

​Event

​Verify the signature

​Acknowledgement and retries

​Polling fallback

Enable delivery

Event

Verify the signature

Acknowledgement and retries

Polling fallback