Webhook Event Overview

Zeal sends webhook events to notify your platform of important state changes in real time. Rather than polling the API for updates, you configure a URL for each event type and Zeal delivers a POST request with a JSON payload whenever that event fires. This makes webhooks the preferred integration pattern for asynchronous workflows like employee onboarding completion or report generation. You configure webhook URLs from the Partner Dashboard → API page → select the relevant event tab. Each event type has its own URL slot, so you can route events to different endpoints in your infrastructure if needed.

Webhook Security

Every webhook request Zeal sends includes a Puzzl-Signature header. This header contains your Webhook Secret, shown in your Partner Dashboard under the API page. Verify it on every incoming request before processing the payload. Verification steps:

Retrieve your Webhook Secret from the Partner Dashboard.
Compare the value of the Puzzl-Signature header on the incoming request to your Webhook Secret.
Reject the request if the values do not match.

Always verify the Puzzl-Signature header before trusting webhook payloads. Failing to do so may expose your system to spoofed events.

Supported Webhook Events

Company Onboarding Event

When it fires: When an employer completes the company onboarding flow through Zeal’s white-label component or API. Use case: Trigger downstream provisioning steps in your platform, such as unlocking payroll features or notifying an account manager. Sample payload:

{
  "event": "company_onboarding",
  "companyID": "fc235f012bae46aa8a082f357715bcfa",
  "onboarded": true,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "companyID": "fc235f012bae46aa8a082f357715bcfa",
    "legal_name": "Pied Piper Inc.",
    "ein": "123456789",
    "onboarded": true
  }
}

Employee Onboarding Event

When it fires: When an employee completes the Employee Onboarding flow through Zeal’s white-label component. Zeal sends the event automatically once the employee’s status is set to onboarded. Use case: Update your platform’s employee records, enable direct deposit, or trigger a welcome communication. Sample payload:

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

See Employee Onboarding Event for the full field reference.

Contractor Event

When it fires: When a 1099 contractor completes the Contractor Onboarding flow through Zeal’s white-label component. Use case: Update contractor records in your platform or trigger 1099 filing preparation. Sample payload:

{
  "event": "contractor_onboarding",
  "contractorID": "ctr_def456",
  "companyID": "fc235f012bae46aa8a082f357715bcfa",
  "onboarded": true,
  "timestamp": "2024-01-17T11:00:00.000Z",
  "data": {
    "contractorID": "ctr_def456",
    "companyID": "fc235f012bae46aa8a082f357715bcfa",
    "first_name": "Monica",
    "last_name": "Hall",
    "email": "monica@piedpiper.com",
    "onboarded": true
  }
}

See Contractor Event for the full field reference.

Job Queue Event (Report Status Change)

When it fires: When an asynchronous report job changes status - most importantly when it transitions to "complete" or "failed". Use case: Trigger your system to download the completed report instead of polling GET /reports in a loop. Sample payload:

{
  "event": "job_queue_status_change",
  "job_id": "7g88a4e0-f2a0-4dc0-9a1c-215e083de5eb",
  "status": "complete",
  "timestamp": "2024-03-25T18:55:00.000Z",
  "data": {
    "job_id": "7g88a4e0-f2a0-4dc0-9a1c-215e083de5eb",
    "status": "complete",
    "payload": "https://api.zeal.com/reports/downloads/7g88a4e0-f2a0-4dc0-9a1c-215e083de5eb",
    "report_format": "payroll_journal",
    "company_id": "fc235f012bae46aa8a082f357715bcfa"
  }
}

See Report Status Webhook for the full field reference.

Setting Up Webhook URLs

Log in to the Partner Dashboard.
Navigate to the API page.
Select the event tab for the webhook you want to configure (e.g., “Employee Onboarding Event”).
Enter your endpoint URL in the field provided.
Save the configuration. Zeal will immediately begin delivering events to that URL.

You should respond to every webhook with an HTTP 200 status code. Zeal may retry delivery if your endpoint returns a non-2xx response.

Introduction

Webhooks

Zeal Components

Companies

Company Onboarding

Reserve Accounts

Customer Accounts (Early Access)

Taxable Locations

Work Locations

Employees

Employee Deduction Templates

Garnishments

Employee Onboarding

Bank Accounts

Custom Attributes

Paperwork API

Employee Checks

Contractors

Contractor Onboarding

Contractor Payment Deductions

Payment Items

Contractor Payments

Paycards

Instant Pay

Employer Checks

Preview

Embedded HR

Reports

Documents

Webhook Event Overview

Webhook Security

Supported Webhook Events

Company Onboarding Event

Employee Onboarding Event

Contractor Event

Job Queue Event (Report Status Change)

Setting Up Webhook URLs

​Webhook Security

​Supported Webhook Events

​Company Onboarding Event

​Employee Onboarding Event

​Contractor Event

​Job Queue Event (Report Status Change)

​Setting Up Webhook URLs

Webhook Security

Supported Webhook Events

Company Onboarding Event

Employee Onboarding Event

Contractor Event

Job Queue Event (Report Status Change)

Setting Up Webhook URLs