Working with Webhooks

Check emits webhooks about many events that happen asynchronously. For example, when payments land (or fail to land) in employee bank accounts, or when Check successfully validates a bank account (or finds it to be invalid), Check will send out webhooks.

But what should you do with those webhooks? To create the best possible payroll product experience—and reduce the number of inbound questions you receive about common edge cases—we recommend using them to trigger in-app or email-based notifications for employers and employees.

📋

Update

Historically, partners relied on these webhooks directly for customer alerts.

Now, the recommended approach for keeping customers informed is to use Check’s Notifications and Communications features wherever supported.

Notifications & Communications

• Notifications – Automatically created by Check for key events that should be communicated to an employer or worker. Partners can consume Notifications via the API to drive their own messaging or opt in to Check-sent Communications.
• Communications – The actual messages (email) sent—either by Check on your behalf or by you using data from Notifications.

For events not yet supported in the Notification and Communication Library, continue to rely on object-specific webhooks for customer-facing alerts.

Key Webhook-Only Use Cases

Some high-impact events are not yet available as Notifications and should still be handled via direct webhook subscriptions. Below is a short list of edge cases that we recommend notifying employers about.

• SSN validations
  There is currently no dedicated SSN validation Notification. You can intercept the Employee webhooks we send and alert employers any time one of their employees is found to have an invalid SSN. This helps prevent end-of-quarter escalations around invalid SSN data.

• Employee and Company Onboard Status
  Check sends webhooks when the onboard_status of a Company, Employee, or Contractor changes. Watch for changes that result in a blocking status and notify employers promptly. This protects your support team from last-minute escalations from employers unaware of their blocking status.

Other Events: Prefer Notifications & Communications

For many other customer-facing alerts, Notifications and Communications replace the need to listen to object-specific webhooks for messaging purposes.

• 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 supports Employer Bank Account Validation Failed and Worker Bank Account Validation Failed notifications. Use these for customer alerts, while continuing to use webhooks for background processing or UI updates.

In addition to payroll funding failures and bank account validation failures, Communications are available for a variety of other employer- and worker-facing events listed in the Notification and Communication Library, such as debit receipts, tax collection variances, and other important changes.

This is a preliminary list of suggestions—there are many more possible notification flows. As you build and release your payroll product, the Check team will work closely with you to set up notification flows for the most important edge cases.