Working with Webhooks

Check emits webhooks about many events that happen asynchronously, from payment processing and bank account validation to employee onboarding status changes. In most integrations, webhooks do two things: keep systems in sync and drive timely customer notifications.

What webhooks are

A webhook is an HTTP POST that Check sends to your endpoint when something changes in our system. You subscribe to the event types you care about, we send a signed request with the payload, and your system updates state or triggers workflows. This avoids polling and reduces the window where your data is out of sync.

Why webhooks matter

Payroll is inherently asynchronous. Funding, onboarding, validations, and filings happen over time and can sometimes change state without a user clicking anything in your app. Webhooks give you near real time awareness of those changes so you can:

• Keep your database consistent with Check
• Update UI state immediately
• Trigger background jobs right when they are needed
• Cut down on noisy polling that can hit rate limits

See The Shape of Your Webhook Endpoint for building reliable, secure handlers: signature verification, retry handling, ordering, and idempotency.

Webhooks vs polling

Webhooks are the default for data sync.

• Near real time - changes in Check are pushed to you immediately, which minimizes time out of sync and reduces errors.
• Efficient - you only receive relevant changes. No change means no traffic.

Polling is a fallback when you cannot accept inbound traffic. It is costly and easy to overuse. If you poll, be mindful of standard API rate limiting: 25 requests per second by default. Bursts above that can return 429 errors and require retries. Details: https://docs.checkhq.com/reference/rate-limiting

Data sync 101

Data sync is the process of keeping two independent systems consistent even though updates can happen on either side.

Partners usually store their own copies of core objects like employees. Some fields overlap with Check and some do not. Your goal is to keep common fields on common objects in sync in both directions.

Example: an employer edits an employee record in your app to reflect a promotion. They change the job title and increase the hourly rate. Job title is important to your app but not required for Check. Hourly rate directly affects payroll.

• When the hourly rate changes in your app, you must send that update to Check so the next payroll uses the correct rate.
• When the job title or profile photo changes, you do not need to update Check because those fields are not used for payroll calculations or filings.
• If the home address changes inside Check during onboarding via a Check Component, consume the employee webhook and update your local record. This keeps tax parameters and location-dependent logic in your app accurate.
• You should not store SSN locally. Still, watch employee webhooks so you can react to SSN validation results and prompt employers to fix issues.

Only set up bidirectional sync for objects you choose to store locally. You do not have to mirror every field. For some objects you may decide Check is the source of truth and only fetch on demand.

Key objects and the events to watch

Use webhooks to mirror create, update, and delete actions and to react to important state changes. The list below is broadly relevant to all partners.

• Workplaces - created, updated, deleted
• Employees - profile changes, onboard_status changes, SSN validation results
• Contractors - profile changes, onboard_status changes
• Bank accounts - validation started, succeeded, or failed
• Employee tax parameters - created or changed
• Company tax parameters - created or changed
• Benefits - created, changed, or ended
• Post-tax deductions - created, changed, or ended
• Custom earning codes - created or changed
• Payrolls and payments - lifecycle transitions like draft to approved, processing to paid, debit initiated, debit failed, return received

A full list of available webhooks is in Webhook Event Types: https://docs.checkhq.com/docs/webhook-event-types

Customer Notifications

📣

Update

Historically, partners used webhooks directly for customer alerts. The recommended approach now is to use Notifications and Communications wherever they are supported. Let Check send templated messages on your behalf, or consume notification records to power your own emails and in-app messages. Continue using webhooks in parallel for background processing and UI updates.

Common examples:

• Payroll funding failure
  When a payroll debit fails, Check creates an Employer Payroll Debit Failed notification. Let Check send the communication automatically, or fetch the notification via the API and send your own. You can still subscribe to related payment webhooks for internal workflows.

• Bank account validation failure
  Check provides Employer Bank Account Validation Failed and Worker Bank Account Validation Failed notifications. Use these for customer alerts, while keeping webhooks for internal sync.

Find supported notifications here: https://docs.checkhq.com/docs/supported-notifications

When to still notify from webhooks

If an event is not yet supported in the Notification and Communication Library, continue to notify customers based on webhooks.

• SSN validations
  There is no dedicated SSN validation notification. Use employee-related webhooks to alert employers when an invalid SSN is detected so they can fix it before filings.

• Employee or company onboard_status
  Watch for transitions into blocking states and inform employers promptly. This prevents last minute escalations.

Library reference: https://docs.checkhq.com/docs/managing-check-to-employer-worker-communication

Implementation checklist

• Map objects and choose which fields you will store locally
• Subscribe to the webhook event types you need
• Build a single, idempotent webhook endpoint with signature verification and retry handling
• Update your local records on create, update, delete, and important state transitions
• Use Notifications and Communications for customer messaging when available, and reserve direct webhook-triggered alerts for gaps
• Add monitoring and alerting so failures are visible and actionable

References

• Webhook Event Types - explore event payloads and decide what to consume: https://docs.checkhq.com/docs/webhook-event-types
• The Shape of Your Webhook Endpoint - how to build secure, reliable handlers: https://docs.checkhq.com/docs/working-with-webhooks
• Notification and Communication Library - supported customer-facing messages: https://docs.checkhq.com/docs/supported-notifications