Webhooks

Use webhooks to receive updates on objects created with the API and to kick off additional workflows based on these events. Each time an event that you subscribed to occurs, Checkr submits a POST request to the designated webhook URL with information about the event. When the include_object option is ON, it also includes the related object.

The User-Agent for the requests will have the prefix Checkr-Webhook/.

To receive webhooks, use the Checkr Dashboard to configure a Webhook URL in the Developer Settings. A maximum of two webhook URLs may be configured. For more information about setting up webhooks, see the Account Settings article in the Checkr Help Center.

{
  "id": "1002d6bca6acdfcbb8442178",
  "object": "event",
  "type": "object.event",
  "created_at": "2018-08-17T01:12:43Z",
  "webhook_url": "https://notify.company.com/checkr",
  "data": {
    "object": {
      "id": "a13f4827d8711ddc75abc56ct",
      "object": "object",
      "uri": "/v1/objects/a13f4827d8711ddc75abc56ct"
    }
  }
}

When include_object is ON, the full related object is included in data.object.

Your endpoint should respond to webhooks as quickly as possible. To acknowledge receipt of a webhook, your endpoint must return a 2xx HTTP status code. This status code should only indicate receipt of the message, not acknowledgment that it was successfully processed by your system. Any other information returned in the response headers or response body is ignored.

If a webhook is not successfully received for any reason, Checkr will continue trying to send it every minute for 10 minutes, then every hour for 24 hours.

Webhook logs can be found on the dashboard: https://dashboard.checkr.com/webhook_logs

Checkr does not guarantee the delivery of events in the order in which they are generated. For example, a report with a result of consider might generate the follow events:

report.completed
report.engaged

Your integration should not expect the delivery of these events to be in this order and should handle this accordingly. For example, you can fetch the report object, and look at report.assessment if you happen to receive the report.completed event later.

For greater security, verify that the requests you receive come from Checkr.

We pass along a hash signature with each request in the header X-Checkr-Signature. The hash signature is generated with the HMAC algorithm, using your API key as a key and SHA256 digest mode. When you receive a request, you can compute a hash and ensure that the one from Checkr matches.

Checkr does not issue a dedicated webhook signing secret. Payloads are signed with the oldest Secret API key on your account. Use that same key as the HMAC secret when verifying signatures.

Example hash signature computation:

printf "$compact_json" | openssl sha256 -hmac "$YOUR_API_KEY"

In this example, $compact_json is the "non-pretty print" version of a JSON object. For example, you can get the compact version of a json file with the jq tool with: compact_json=$(jq -c < example_response.json).

Note: Accounts without an API key will have X-Checkr-Signature set to "Please create an API key to check the authenticity of our webhooks."

Code examples on how to do this can be found here.

While webhooks are helpful for updates, they are not foolproof. In some cases, report updates can be sent in rapid succession based on multiple events within the Checkr environment, and may be "mis-heard". For robust webhook handling, we recommend that you account for the following:

• Duplicate reports (idempotency)
• Webhook misses

As a best practice, Checkr recommends that you build a safety net to account for duplicate reports. One option might be to build in a function ahead of the status tracker, which copies only one report.completed update per Candidate or Report. This works well with an additional time threshold assigned. (For example, a report is only considered a duplicate if it's within 60 minutes of a previous iteration of that report.)

To address missed webhook updates, you may also consider adding a function to send an alert if no report.completed update is sent within a certain number of days.

{
  "type": "candidate.created",
  "data": { "object": { "id": "c373384e71a9a02098cb7421", "object": "candidate", ... } }
}

Verification events are issued during the Exception process when a candidate is issued or has responded to a request to verify submitted PII.

Verification events are issued for exceptions which occur to ask candidates to confirm their Social Security Number, Driver License information, or Education and Employment Verification information.

The list of possible verification types that are in the webhook payload (verification_type inside the data object) can be found here.

{
  "type": "report.completed",
  "data": {
    "object": {
      "id": "4722c07dd9a10c3985ae432a",
      "status": "complete",
      "result": "clear",
      "package": "driver_pro"
    }
  }
}