Receive deduction webhooks and report employment changes to keep Benbase in sync.

Sync Data

After providing census data, employees can enroll in benefits. You need to handle two things:

Deduction webhooks — receive payroll deduction data as employees enroll
Employment changes — report new hires, terminations, address changes, and compensation changes

Deduction Webhooks

When employees select their benefits, Benbase calculates the payroll deductions — how much the employee and employer each pay per period. You receive these as employee.deduction-updated webhooks.

Use upsert operations (update if exists, insert if not) — the same event type covers both new deductions and modifications.

Webhook payload

{
  "created_at": "2024-07-01T05:31:56Z",
  "data": {
    "id": "<deduction-id>",
    "employee_id": "<employee-id>",
    "line_of_coverage": "medical",
    "member_contribution": "150.00",
    "employer_contribution": "450.00",
    "period": "monthly",
    "taxability": "pre_tax",
    "coverage_type": "member_family",
    "description": "Blue Cross PPO",
    "effective_start": "2024-07-01T00:00:00Z",
    "effective_end": "2025-06-30T00:00:00Z"
  },
  "event_type": "employee.deduction-updated",
  "id": "<webhook-event-id>"
}

Webhook fields

Field	Type	Description
`created_at`	string	When the event was sent (ISO 8601)
`event_type`	string	`employee.deduction-updated`
`id`	string	Unique webhook event ID

Deduction data fields

Field	Type	Required	Description	Possible Values
`id`	string	Yes	Deduction ID
`employee_id`	string	Yes	Employee ID
`line_of_coverage`	string	Yes	Benefit type	`medical`, `dental`, `vision`, `life`, `accident`, `accidental_death`, `cancer`, `hospital_indemnity`, `hsa`, `healthcare_fsa`, `dependent_care_fsa`, `limited_purpose_fsa`, `long_term_disability`, `short_term_disability`, `voluntary_critical_illness`, `voluntary_life`, `voluntary_accidental_death`, `voluntary_short_term_disability`
`member_contribution`	string	Yes	Employee's contribution amount
`employer_contribution`	string	Yes	Employer's contribution amount
`period`	string	Yes	Deduction frequency	`weekly`, `biweekly`, `semimonthly`, `monthly`
`taxability`	string	Yes	Tax treatment	`pre_tax`, `post_tax`
`coverage_type`	string	No	Who is covered	`member`, `member_spouse`, `member_child`, `member_children`, `member_family`
`description`	string	No	Plan description
`effective_start`	string	No	When deduction starts (ISO 8601)
`effective_end`	string	No	When deduction ends (ISO 8601)

The employee.deduction-created event is deprecated. Use employee.deduction-updated for all deduction changes, including new deductions.

Employment Changes

Benbase needs to know when employees join, leave, move, or change compensation — these events affect benefits eligibility and rates. Report them as they happen using the endpoints below.

New Hire

POST /employee-changes/new-hire — Call when a new employee is added to an existing employer.

Required fields:

Field	Type	Description
`employer_id`	string	Your internal employer ID
`employee_id`	string	Your internal employee ID
`first_name`	string	Max 255 characters
`last_name`	string	Max 255 characters
`dob`	string	YYYY-MM-DD format
`address`	object	See Address fields
`hire_date`	string	YYYY-MM-DD format
`email`	string	Valid email, max 254 characters
`hours_worked`	string	Hours per week
`pay_rate`	array	See Pay Rate fields
`employment_status`	string	`full_time` or `part_time`

Optional fields:

Field	Type	Description
`ssn`	string	Social Security Number
`phone_number`	string	Max 10 characters
`biological_sex`	string	`male` or `female`
`pay_frequency`	string	`weekly`, `biweekly`, `semimonthly`, or `monthly`
`job_title`	string	Max 255 characters

If you have a personal email address, use that one as benefits could continue after employment ends. If not, use work email instead.

curl -X POST https://embed-sandbox.benbase.com/api/employee-changes/new-hire \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "employer_id": "<employer-id>",
    "employee_id": "<employee-id>",
    "first_name": "<first-name>",
    "last_name": "<last-name>",
    "dob": "<YYYY-MM-DD>",
    "address": {
      "line1": "<address-line1>",
      "line2": "<address-line2>",
      "city": "<city>",
      "state": "<state-code>",
      "zip_code": "<zip-code>"
    },
    "hire_date": "<YYYY-MM-DD>",
    "email": "<employee-email>",
    "hours_worked": "<hours-per-week>",
    "pay_rate": [{
      "amount": "<amount>",
      "period": "annually",
      "effective_start": "<YYYY-MM-DD>"
    }],
    "employment_status": "full_time"
  }'

Termination

POST /employee-changes/termination — Call when an employee is leaving the company. Benbase handles all post-termination processes (COBRA, etc.) automatically.

Field	Type	Required	Description
`employee_id`	string	Yes	Employee ID
`termination_date`	string	Yes	YYYY-MM-DD format

curl -X POST https://embed-sandbox.benbase.com/api/employee-changes/termination \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "<employee-id>",
    "termination_date": "<YYYY-MM-DD>"
  }'

Demographic Update (Address Change)

POST /employee-changes/demographic — Call when an employee moves to a different address or state. Address changes can affect benefits eligibility and rates.

Field	Type	Required	Description
`employee_id`	string	Yes	Employee ID
`address`	object	Yes	See Address fields

curl -X POST https://embed-sandbox.benbase.com/api/employee-changes/demographic \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "<employee-id>",
    "address": {
      "line1": "<address-line1>",
      "line2": "<address-line2>",
      "city": "<city>",
      "state": "<state-code>",
      "zip_code": "<zip-code>"
    }
  }'

Compensation Change

POST /employee-changes/compensation-change — Call when an employee's pay rate, pay frequency, or employment status changes. At least one field (besides employee_id) must be provided.

Field	Type	Required	Description
`employee_id`	string	Yes	Employee ID
`pay_frequency`	string	No	`weekly`, `biweekly`, `semimonthly`, or `monthly`
`pay_rate`	object	No	See Pay Rate fields
`employment_status`	string	No	`full_time`, `part_time`, or `variable_hours`

curl -X POST https://embed-sandbox.benbase.com/api/employee-changes/compensation-change \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "<employee-id>",
    "pay_frequency": "biweekly",
    "pay_rate": {
      "amount": "<amount>",
      "period": "annually",
      "effective_start": "<YYYY-MM-DD>"
    },
    "employment_status": "full_time"
  }'

Shared Field Definitions

Address fields

Field	Type	Required	Description
`line1`	string	Yes	Primary address line
`line2`	string	No	Apartment, suite, etc.
`city`	string	Yes	City name
`state`	string	Yes	Two-letter state code (e.g. `NY`, `CA`, `TX`)
`zip_code`	string	Yes	ZIP code

Pay Rate fields

Field	Type	Required	Description
`amount`	string	Yes	Pay amount, rounded to 2 decimal places (e.g. `"75000.00"`)
`period`	string	Yes	`annually` or `hourly`
`effective_start`	string	Yes	When the rate takes effect (YYYY-MM-DD)

Next step

→ Embed Employee Flow

3. Sync Data