Webhooks

Webhooks let your application receive real-time HTTP notifications when events occur in Vitable — such as an enrollment being accepted, an employee being created, or a payroll deduction being generated.

Instead of polling the API for changes, register a webhook endpoint and Vitable will POST event data to your URL as things happen.

How It Works

1. You register a webhook endpoint URL with Vitable
2. When an event occurs, Vitable sends a POST request to your endpoint
3. Your server processes the event and responds with a 2xx status code
4. If delivery fails, Vitable retries with exponential backoff

Payload Format

All webhook events use a standardized payload schema:

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

event_id string Prefixed identifier for this event (e.g., wevt_...). Use this for idempotency — your system may receive the same event more than once.

organization_id string The organization this event belongs to. Use this to route events when managing multiple employers.

event_name string The event type, formatted as {resource}.{action} (e.g., enrollment.accepted).

resource_type string The type of resource affected (e.g., enrollment, employee).

resource_id string The prefixed ID of the affected resource. Use this to fetch the current state from the API.

created_at ISO 8601 (UTC) When the event occurred. All timestamps are in UTC.