Skip to navigation
Embedded BenefitsConcepts

Payroll Deductions

How to receive employee deduction events and fetch deduction data for payroll integration.

Vitable generates payroll deduction statements on a monthly schedule. On the 1st of each month, a scheduled process calculates deductions for all employers with active enrollments and fires employee.deduction_created webhook events. This page explains how to listen for that event, retrieve the deduction details from the employee resource, and apply them in your payroll system.

Quick Reference

EventWhat It MeansYour ActionEndpoint
employee.deduction_createdDeductions were generated during the monthly statement cycleFetch the employee to get deduction detailsGET /v1/employees/{id}

Deduction Flow Overview

Flow summary:

  1. On the 1st of each month, Vitable runs a scheduled process that generates payroll deduction statements for all employers with active enrollments.
  2. For each employee with active coverage, Vitable calculates deduction amounts based on their enrolled benefits.
  3. Vitable delivers an employee.deduction_created webhook per employee to your endpoint.
  4. You use the resource_id from the webhook payload to fetch the employee and read the deductions array.
  5. You apply those deductions to your payroll system for the new period.

Receiving Deduction Events

When Vitable delivers an employee.deduction_created event, the webhook payload follows the standard format:

{
  "event_id": "wevt_550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "org_xyz789",
  "event_name": "employee.deduction_created",
  "resource_type": "employee",
  "resource_id": "empl_7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "created_at": "2026-01-23T14:30:00+00:00"
}

The resource_id is the employee ID (prefixed with empl_), and the resource_type is employee.

The employee.deduction_created event does not fire immediately after enrollment confirmation. Deductions are generated by a monthly scheduled process that runs on the 1st of each month. The event fires once per employee per statement period for all employees with active enrollments.

Fetching Employee Deductions

Deductions are not a standalone API resource — they are a nested property on the employee resource. After receiving the webhook, fetch the employee using GET /v1/employees/{id} with the resource_id from the payload:

curl -X GET https://api.vitablehealth.com/v1/employees/empl_7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer $VITABLE_API_KEY" \
  -H "Content-Type: application/json"

The employee response includes a deductions array with the current period’s payroll deduction details:

FieldDescription
deduction_amount_in_centsThe amount to deduct from the employee’s paycheck, in cents
tax_classificationTax treatment: Pre-tax, Post-tax, or Unknown
frequencyDeduction frequency (e.g., monthly)
benefit_nameThe name of the benefit plan this deduction is for
deduction_categoryDeduction category (reserved for future use)
period_start_dateStart date of the deduction period (YYYY-MM-DD)
period_end_dateEnd date of the deduction period (YYYY-MM-DD)

The deductions array reflects a snapshot of the current statement period. When a new deduction statement is generated, the previous period’s deductions are replaced. Always fetch fresh data after receiving the webhook rather than relying on cached values.

Handling Deductions in Your System

A typical integration flow looks like this:

  1. Receive the employee.deduction_created webhook and respond with a 2xx status code immediately.
  2. Fetch the employee using the resource_id to get the current deductions array.
  3. Match the employee in your payroll system using the employee id or reference_id.
  4. Record each entry in the deductions array as a payroll deduction, noting the tax_classification and frequency.
  5. Apply the deductions for the period defined by period_start_date and period_end_date.

Always fetch the employee data after receiving the webhook rather than caching amounts from earlier API calls. Deduction amounts may change when a new statement period is generated.

Troubleshooting

Missed webhook events — If your endpoint was down when the event fired, Vitable retries delivery with exponential backoff for up to ~3.4 days. You can also query missed events using GET /v1/webhook-events to recover. See Reliability for full retry details.

Duplicate events — Your endpoint may receive the same employee.deduction_created event more than once. Use the event_id field to deduplicate and ensure you do not apply the same deduction twice.

Empty deductions array — In rare cases, the deductions may not be immediately available when you fetch the employee. If the deductions array is empty, implement a short retry with backoff before fetching again.

Use GET /v1/webhook-events/{event_id}/deliveries to check the delivery status of a specific event if you suspect your endpoint missed it.

EventDescription
employee.deduction_createdPayroll deductions have been generated for an employee.
enrollment.acceptedAn enrollment has been accepted and is now active. Learn more
enrollment.grantedAn enrollment has been granted. Learn more
enrollment.terminatedAn enrollment has been terminated and coverage has ended. Learn more

For the full list of webhook events, see Webhook Events.