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

# Contractor Event

> Details on the Contractor Event webhook - when it fires, the full payload schema, and how to configure your receiving endpoint in the Partner Dashboard.

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.

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

***

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

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

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

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

<ResponseField name="companyID" type="string">
  The ID of the company this contractor is associated with.
</ResponseField>

<ResponseField name="onboarded" type="boolean">
  Always `true` when this event fires, confirming the contractor's 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 contractor record at the time of the event.

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

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

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

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

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

    <ResponseField name="type" type="string">
      Whether the contractor is an `"individual"` or a `"business"` entity.
    </ResponseField>

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

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

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

***

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

1. Log in to the **Partner Dashboard**.
2. Navigate to the **API** page.
3. Click the **Contractor Event** tab.
4. Enter your receiving endpoint URL.
5. Save. Zeal begins delivering contractor onboarding events to that URL immediately.