Deduction Changes
When employees enroll in or modify their benefit deductions, Benbase automatically sends webhooks to keep your system synchronized with these changes in real-time.
What are Deduction Changes?
Deduction changes occur when:
- An employee enrolls in a new benefit (deduction created)
- An employee modifies their existing benefit enrollment (deduction updated)
- Changes to contribution amounts, coverage types, or effective dates
These webhooks ensure your payroll and HR systems stay up-to-date with the latest benefit enrollment information.
Webhook Events
Benbase sends the following webhook events for deduction changes:
- Deprecated
employee.deduction-created- Triggered when a new deduction is created for an employee. This event will be deprecated in the future. employee.deduction-updated- Triggered when a deduction is modified or created
For information on setting up webhooks and managing them through the Svix portal, see the Webhooks documentation.
The employee.deduction-created event is deprecated. Please use employee.deduction-updated for all deduction changes, including new deductions.
When receiving deductions via webhooks, you should use upsert operations (update if exists, insert if not) to handle both created and updated events. This ensures your system stays synchronized regardless of whether a deduction is new or modified.
Webhook Payload
Here's an example of the webhook payload structure:
{
"created_at": "2024-07-01T05:31:56Z",
"data": {
"coverage_type": "member",
"description": "Principal Vision (VSP Choice Network)",
"effective_end": "2025-12-31T05:31:56Z",
"effective_start": "2024-07-01T05:31:56Z",
"employee_id": "emp_LRgFZ2uXBSVsR6Q0g9Q54",
"employer_contribution": "1.84",
"id": "pben_tqYzdjv7yzbKX6m5Bf80P",
"line_of_coverage": "accident",
"member_contribution": "0.46",
"period": "monthly",
"taxability": "pre_tax"
},
"event_type": "employee.deduction-created",
"id": "wh_tqYaajv7yzbKX6m5Bf80P"
}
You can also access and view example payloads inside the Svix portal directly.
Webhook Payload Fields
The webhook payload contains the following top-level fields:
| Field | Type | Required | Description |
|---|---|---|---|
created_at | string | Yes | Timestamp when the event was sent (ISO 8601 format) |
data | object | Yes | The deduction data object |
event_type | string | Yes | The type of event (e.g., employee.deduction-updated) |
id | string | Yes | Unique identifier for the webhook event |
Payroll Deduction Fields
The data object contains the following fields:
| Field | Type | Required | Description | Possible Values |
|---|---|---|---|---|
id | string | Yes | ID of the deduction | - |
employee_id | string | Yes | Employee ID | - |
line_of_coverage | string | Yes | The line of coverage | accident, accidental_death, cancer, dental, dependent_care_fsa, healthcare_fsa, hospital_indemnity, hsa, life, limited_purpose_fsa, long_term_disability, medical, short_term_disability, vision, voluntary_critical_illness, voluntary_life, voluntary_accidental_death, voluntary_short_term_disability |
member_contribution | string | Yes | How much the employee contributes | - |
employer_contribution | string | Yes | How much the employer contributes | - |
period | string | Yes | When the deductions happen | weekly, biweekly, semimonthly, monthly |
taxability | string | Yes | Deduction tax status | pre_tax, post_tax |
coverage_type | string | No | Coverage type | member, member_spouse, member_child, member_children, member_family |
description | string | No | Description of deduction | - |
effective_start | string | No | When the deduction starts applying (ISO 8601 timestamp) | - |
effective_end | string | No | When the deduction stops applying (ISO 8601 timestamp) | - |