Employee Onboarding Event

The Employee Onboarding Event is a webhook Zeal sends to your platform when an employee successfully completes the onboarding flow. This event fires automatically when the employee’s onboarded status is set to true - either programmatically via the API (POST /employees/setOnboardedStatusToTrue) or when the employee completes the white-label Employee Onboarding component. Use this event to synchronize your platform’s employee records, enable downstream features like direct deposit, or send the employee a welcome notification without polling the Zeal API.

Configure your webhook URL in the Partner Dashboard → API page → Employee Onboarding Event tab. Zeal will POST the payload to that URL every time an employee in any of your companies completes onboarding.

When the Event Fires

The Employee Onboarding Event is triggered when:

A partner or admin calls POST /employees/setOnboardedStatusToTrue via the API.
An employee completes the self-service white-label Employee Onboarding flow (which automatically sets onboarded to true upon successful completion).

Webhook Request

Zeal sends an HTTP POST to your configured endpoint with a Content-Type: application/json header and a Puzzl-Signature header containing your Webhook Secret. Verify the request by checking that the Puzzl-Signature value matches your Webhook Secret from the Partner Dashboard before processing the event. Headers

Header	Description
`Content-Type`	`application/json`
`Puzzl-Signature`	Contains your Webhook Secret; verify it matches the secret shown in your Partner Dashboard

Payload Schema

Example Payload

{
  "event": "employee_onboarding",
  "employeeID": "emp_6547etrc312314213",
  "companyID": "fc235f012bae46aa8a082f357715bcfa",
  "onboarded": true,
  "timestamp": "2024-01-16T09:15:32.000Z",
  "data": {
    "employeeID": "emp_6547etrc312314213",
    "companyID": "fc235f012bae46aa8a082f357715bcfa",
    "first_name": "Richard",
    "last_name": "Hendricks",
    "email": "richard@piedpiper.com",
    "onboarded": true,
    "created_at": "2024-01-10T08:00:00.000Z",
    "updated_at": "2024-01-16T09:15:32.000Z"
  }
}

Top-level Fields

string

Always "employee_onboarding" for this event type.

string

The unique Zeal identifier for the employee who completed onboarding.

string

The ID of the company this employee belongs to.

boolean

Always true when this event fires, confirming that onboarding is complete.

string

The ISO 8601 datetime at which the event was generated.

object

A snapshot of the employee record at the time of the event.

Show data fields

string

The unique identifier for the employee.

string

The ID of the employer company.

string

The employee’s first name.

string

The employee’s last name.

string

The employee’s email address.

boolean

The employee’s onboarding status (true when fully onboarded).

string

The ISO 8601 datetime when the employee record was created.

string

The ISO 8601 datetime when the employee record was last updated.

Responding to the Event

Your endpoint must return an HTTP 200 status code to acknowledge receipt. If Zeal does not receive a 200 response, it may retry delivery. Process the event idempotently so that duplicate deliveries do not cause duplicate side effects in your system.

Configuring the Webhook URL

Log in to the Partner Dashboard.
Navigate to the API page.
Click the Employee Onboarding Event tab.
Enter your endpoint URL.
Save. Zeal will start delivering events to that URL immediately.

Introduction

Webhooks

Zeal Components

Companies

Company Onboarding

Reserve Accounts

Customer Accounts (Early Access)

Taxable Locations

Work Locations

Employees

Employee Deduction Templates