> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Employee Onboarding Event

> Details on the Employee Onboarding webhook event - when it fires, the full payload schema, and how to configure your receiving endpoint in Zeal.

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.

<Note>
  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.
</Note>

***

## 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**

```json theme={null}
{
  "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**

<ResponseField name="event" type="string">
  Always `"employee_onboarding"` for this event type.
</ResponseField>

<ResponseField name="employeeID" type="string">
  The unique Zeal identifier for the employee who completed onboarding.
</ResponseField>

<ResponseField name="companyID" type="string">
  The ID of the company this employee belongs to.
</ResponseField>

<ResponseField name="onboarded" type="boolean">
  Always `true` when this event fires, confirming that onboarding is complete.
</ResponseField>

<ResponseField name="timestamp" type="string">
  The ISO 8601 datetime at which the event was generated.
</ResponseField>

<ResponseField name="data" type="object">
  A snapshot of the employee record at the time of the event.

  <Expandable title="data fields">
    <ResponseField name="employeeID" type="string">
      The unique identifier for the employee.
    </ResponseField>

    <ResponseField name="companyID" type="string">
      The ID of the employer company.
    </ResponseField>

    <ResponseField name="first_name" type="string">
      The employee's first name.
    </ResponseField>

    <ResponseField name="last_name" type="string">
      The employee's last name.
    </ResponseField>

    <ResponseField name="email" type="string">
      The employee's email address.
    </ResponseField>

    <ResponseField name="onboarded" type="boolean">
      The employee's onboarding status (`true` when fully onboarded).
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The ISO 8601 datetime when the employee record was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      The ISO 8601 datetime when the employee record was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## 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

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