> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.vitablehealth.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.vitablehealth.com/_mcp/server.

# Events

> All webhook event types and when they are triggered.

Events follow the naming convention `{resource}.{action}`.

## Enrollment

| Event                   | Description                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| `enrollment.accepted`   | An enrollment has been accepted. [Learn more](/embedded_benefits/concepts/enrollment-lifecycle)   |
| `enrollment.terminated` | An enrollment has been terminated. [Learn more](/embedded_benefits/concepts/enrollment-lifecycle) |
| `enrollment.elected`    | An employee has elected a benefit. [Learn more](/embedded_benefits/concepts/enrollment-lifecycle) |
| `enrollment.granted`    | An enrollment has been granted. [Learn more](/embedded_benefits/concepts/enrollment-lifecycle)    |
| `enrollment.waived`     | An employee has waived a benefit. [Learn more](/embedded_benefits/concepts/enrollment-lifecycle)  |
| `enrollment.started`    | An enrollment has started. [Learn more](/embedded_benefits/concepts/enrollment-lifecycle)         |

## Employee

| Event                             | Description                                                                                                              |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `employee.eligibility_granted`    | An employee has been granted benefits eligibility. [Learn more](/embedded_benefits/concepts/employee-lifecycle)          |
| `employee.eligibility_terminated` | An employee's benefits eligibility has been terminated. [Learn more](/embedded_benefits/concepts/employee-lifecycle)     |
| `employee.deactivated`            | An employee has been deactivated. [Learn more](/embedded_benefits/concepts/employee-lifecycle)                           |
| `employee.deduction_created`      | A new payroll deduction has been generated for an employee. [Learn more](/embedded_benefits/concepts/payroll-deductions) |

## Understanding Event Flows

The diagram below shows how all webhook events relate to each other across resource types. Each event is grouped by its resource.

```mermaid
sequenceDiagram
    participant P as Partner
    participant V as Vitable API
    P->>V: Census sync employees
    V--)P: employee.eligibility_granted (per employee)
    Note over V: Employee opens enrollment
    V--)P: enrollment.started
    alt Employee enrolls
        V--)P: enrollment.elected + enrollment.accepted
    else Employee declines
        V--)P: enrollment.waived
    end
    Note over V: Monthly deduction cycle (1st of each month)
    V--)P: employee.deduction_created (per employee)
    Note over V: If employee is later terminated
    V--)P: employee.eligibility_terminated
    V--)P: enrollment.terminated (per enrollment)
    V--)P: employee.deactivated
```

**Event flow summary:**

* **Employee eligibility** events (`employee.eligibility_granted`, `employee.eligibility_terminated`) signal when employees can or can no longer enroll.
* **Enrollment** events track the full benefit selection lifecycle from `enrollment.started` through `enrollment.accepted` or `enrollment.waived`.
* **Payroll deductions** (`employee.deduction_created`) are generated on a monthly schedule for employees with active enrollments.
* **Employee deactivation** (`employee.deactivated`) occurs after termination and may trigger enrollment terminations.

## Related Resources

* [Employer Onboarding](/embedded_benefits/guides/employer-onboarding) — end-to-end integration setup
* [Employee Lifecycle](/embedded_benefits/concepts/employee-lifecycle) — employee statuses and eligibility events
* [Enrollment Lifecycle](/embedded_benefits/concepts/enrollment-lifecycle) — enrollment statuses and transitions
* [Census Sync](/embedded_benefits/concepts/census-sync) — submitting and monitoring employee data
* [Payroll Deductions](/embedded_benefits/concepts/payroll-deductions) — processing payroll deduction events