Contractor Event

The Contractor Event is a webhook Zeal sends to your platform when a 1099 contractor completes the onboarding flow. It fires automatically when the contractor finishes the white-label Contractor Onboarding component, signaling that their personal information and W-9 data have been collected and their onboarded status is now true. Use this event to update contractor records in your platform, trigger 1099 filing preparation steps, or unlock payment capabilities without polling the Zeal API for status changes.

Configure your webhook URL in the Partner Dashboard → API page → Contractor Event tab. Zeal delivers the payload to your URL every time a contractor in any of your companies completes onboarding.

When the Event Fires

The Contractor Event is triggered when a contractor successfully completes the self-service white-label Contractor Onboarding flow. Zeal automatically sets the contractor’s onboarded field to true and sends this webhook immediately afterward.

Webhook Request

Zeal sends an HTTP POST to your configured endpoint with a Content-Type: application/json header and a Puzzl-Signature header for verification. Check that the Puzzl-Signature value matches your Webhook Secret from the Partner Dashboard before processing the payload. 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": "contractor_onboarding",
  "contractorID": "ctr_abc789def012",
  "companyID": "fc235f012bae46aa8a082f357715bcfa",
  "onboarded": true,
  "timestamp": "2024-01-17T11:22:45.000Z",
  "data": {
    "contractorID": "ctr_abc789def012",
    "companyID": "fc235f012bae46aa8a082f357715bcfa",
    "first_name": "Monica",
    "last_name": "Hall",
    "email": "monica@piedpiper.com",
    "type": "individual",
    "onboarded": true,
    "created_at": "2024-01-12T14:00:00.000Z",
    "updated_at": "2024-01-17T11:22:45.000Z"
  }
}

Top-level Fields

string

Always "contractor_onboarding" for this event type.

string

The unique Zeal identifier for the contractor who completed onboarding.

string

The ID of the company this contractor is associated with.

boolean

Always true when this event fires, confirming the contractor’s onboarding is complete.

string

The ISO 8601 datetime at which the event was generated.

object

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

Show data fields

string

The unique identifier for the contractor.

string

The ID of the employer company this contractor works for.

string

The contractor’s first name.

string

The contractor’s last name.

string

The contractor’s email address.

string

Whether the contractor is an "individual" or a "business" entity.

boolean

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

string

The ISO 8601 datetime when the contractor record was created.

string

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

Responding to the Event

Return an HTTP 200 status code to acknowledge receipt of the webhook. If your endpoint returns a non-2xx response, Zeal may retry delivery. Ensure your event handler is idempotent so that retried deliveries do not produce duplicate side effects.

Configuring the Webhook URL

Log in to the Partner Dashboard.
Navigate to the API page.
Click the Contractor Event tab.
Enter your receiving endpoint URL.
Save. Zeal begins delivering contractor onboarding 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

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

When the Event Fires

Webhook Request

Payload Schema

Responding to the Event

Configuring the Webhook URL

​When the Event Fires

​Webhook Request

​Payload Schema

​Responding to the Event

​Configuring the Webhook URL

When the Event Fires

Webhook Request

Payload Schema

Responding to the Event

Configuring the Webhook URL