Webhooks

The lifecycle of a payroll generally plays out over the course of several days, due to the asynchronous payment processing handled by Check. Once a customer approves a payroll, it moves through a series of states: pending, processing, and paid. Keeping track of when a payroll makes these state transitions can be cumbersome because it requires polling the Check API to look for changes. To make this easier, we’re introducing webhooks. By configuring webhooks, you can enable Check to send you real-time HTTP updates about events that happen in our system. At launch, we support sending webhooks for payroll status updates, but more event types will be added in the coming months.

To begin receiving webhooks, create a webhook configuration like so:

This request will create a webhook config object which you can inspect by issuing a GET request to /webhook_configs:

You can create multiple webhook config objects in our sandbox and production environments. We will send a webhook request to each configured URL in the environment where an event originates. If we fail to deliver a request due to either a non-2XX response code or a timeout, we will periodically reattempt delivery for four days.

All webhook config objects have a unique secret key. The purpose of the secret key is to provide a way to verify the authenticity of our webhook requests. Each webhook request that we send bears a X-Signature header. The signature is base-16 encoded and can be replicated by applying the HMAC-SHA-256 hash algorithm to the body of the webhook with your specific webhook key. For more information about webhook authentication and webhooks in general, please refer to our webhook documentation.