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