Payroll Deductions

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

Event	What It Means	Your Action	Endpoint
employee.deduction_created	Deductions were generated during the monthly statement cycle	Fetch the employee to get deduction details	GET /v1/employees/{id}

Deduction Flow Overview

sequenceDiagram
    participant V as Vitable API
    participant P as Partner
    Note over V: 1st of each month — scheduled deduction generation
    Note over V: Deductions calculated for all active enrollments
    V--)P: webhook: employee.deduction_created (per employee)
    P->>V: GET /v1/employees/{id}
    V-->>P: 200 Employee with deductions
    Note over P: Apply deductions to payroll

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:

Field	Description
deduction_amount_in_cents	The amount to deduct from the employee’s paycheck, in cents
tax_classification	Tax treatment: Pre-tax, Post-tax, or Unknown
frequency	Deduction frequency (e.g., monthly)
benefit_name	The name of the benefit plan this deduction is for
deduction_category	Deduction category (reserved for future use)
period_start_date	Start date of the deduction period (YYYY-MM-DD)
period_end_date	End 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.

Related Webhooks

Event	Description
employee.deduction_created	Payroll deductions have been generated for an employee.
enrollment.accepted	An enrollment has been accepted and is now active. Learn more
enrollment.granted	An enrollment has been granted. Learn more
enrollment.terminated	An enrollment has been terminated and coverage has ended. Learn more

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

Related API Endpoints

• GET /v1/employees/{id} — Retrieve employee details including the deductions array
• GET /v1/employees/{id}/enrollments — List all enrollments for an employee
• GET /v1/webhook-events — Query webhook events to recover missed deliveries
• GET /v1/webhook-events/{event_id} — Retrieve a specific webhook event
• GET /v1/webhook-events/{event_id}/deliveries — Check delivery status for a webhook event