{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-apis/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Webhooks","description":"Checkr developer documentation for background check APIs, embeds, and partner integrations."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhooks","__idx":0},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["include_object"]}," option is ON, it also includes the related object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The User-Agent for the requests will have the prefix ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Checkr-Webhook/"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To receive webhooks, use the Checkr Dashboard to configure a Webhook URL in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.checkr.com/account/developer_settings"},"children":["Developer Settings"]},". A maximum of two webhook URLs may be configured. For more information about setting up webhooks, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://help.checkr.com/hc/en-us/articles/360010450474-Account-Settings#developer"},"children":["Account Settings article"]}," in the Checkr Help Center."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Any webhook URL that fails to accept with a 2XX status code at least one request over a period of 60 days will be removed automatically - e.g. webhooks failing for 100% of the requests during 60 or more days. However if no requests have reached into a webhook URL, over the same period of time, it won't be removed."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhook-payload-structure","__idx":1},"children":["Webhook payload structure"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"1002d6bca6acdfcbb8442178\",\n  \"object\": \"event\",\n  \"type\": \"object.event\",\n  \"created_at\": \"2018-08-17T01:12:43Z\",\n  \"webhook_url\": \"https://notify.company.com/checkr\",\n  \"data\": {\n    \"object\": {\n      \"id\": \"a13f4827d8711ddc75abc56ct\",\n      \"object\": \"object\",\n      \"uri\": \"/v1/objects/a13f4827d8711ddc75abc56ct\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["include_object"]}," is ON, the full related object is included in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.object"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"attributes","__idx":2},"children":["Attributes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ID of the event."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Defines the object type: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The type of event. Values include: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate.created"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.completed"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["timestamp iso 8601 format"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp for the event."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Webhook URL."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["hash"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object associated with the event."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["include_object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Should the related object be attached to webhook payload."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-webhook-url-formats","__idx":3},"children":["Supported webhook URL formats"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Format"},"children":["Format"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HTTPS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://(<user>:<password>@)<hostname>/<path>"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"E.g.: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://notify.company.com/checkr"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Notes:"]}," The endpoint to be reached must be public.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Webhook URLs must be HTTPS.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Basic Auth is supported by adding ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username:password@"]}," in front of the hostname, credentials must be URL escaped."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SNS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sns://<key_id>:<access_key>@<region>/<topic_owner>/<topic_name>"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"E.g.: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sns://AKI95AMUAD5K:a2n66fVKX7%2BYJKid3@us-east-1/12048/checkr"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["AWS Simple Notification System (SNS)",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Notes:"]}," Access Key must have ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["only"]}," the Publish to SNS right in IAM.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Credentials must be URL escaped."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"responding-to-webhooks","__idx":4},"children":["Responding to webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your endpoint should respond to webhooks as quickly as possible. To acknowledge receipt of a webhook, your endpoint must return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhook logs can be found on the dashboard: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.checkr.com/webhook_logs"},"children":["https://dashboard.checkr.com/webhook_logs"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"order-of-events","__idx":5},"children":["Order of events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr does not guarantee the delivery of events in the order in which they are generated. For example, a report with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["consider"]}," might generate the follow events:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"report.completed\nreport.engaged\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.assessment"]}," if you happen to receive the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.completed"]}," event later."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"securing-webhooks","__idx":6},"children":["Securing webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For greater security, verify that the requests you receive come from Checkr."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr does not issue a dedicated webhook signing secret. Payloads are signed with the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["oldest Secret API key"]}," on your account. Use that same key as the HMAC secret when verifying signatures."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not delete your oldest Secret API key. Because it is the key used to sign webhooks, deleting it will break signature verification for all incoming events. If you must rotate it, update your verification logic to the new signing key first."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example hash signature computation:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"printf \"$compact_json\" | openssl sha256 -hmac \"$YOUR_API_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jq"]}," tool with: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["compact_json=$(jq -c < example_response.json)"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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.\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Code examples on how to do this can be found ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/checkr/webhook-verification-examples/"},"children":["here"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"guarding-against-duplicate-and-missed-report-notifications","__idx":7},"children":["Guarding against duplicate and missed report notifications"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Duplicate reports (idempotency)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Webhook misses"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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.)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To address missed webhook updates, you may also consider adding a function to send an alert if no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.completed"]}," update is sent within a certain number of days."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-types","__idx":8},"children":["Event types"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"candidate-events","__idx":9},"children":["Candidate events"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"candidate.created\",\n  \"data\": { \"object\": { \"id\": \"c373384e71a9a02098cb7421\", \"object\": \"candidate\", ... } }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate.created"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A new Candidate has been created."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate.id_required"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An exception has been raised requiring a copy of the Candidate's identification."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate.driver_abstract_required"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An exception has been raised requiring a Candidate's driver abstract."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate.driver_license_required"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An exception has been raised requiring a copy of the Candidate's driver license."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate.updated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Candidate has been updated."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate.pre_adverse_action"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An Adverse Action has been initiated on the Candidate."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate.post_adverse_action"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An Adverse Action has been completed on the Candidate."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"invitation-events","__idx":10},"children":["Invitation events"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invitation.created"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An Invitation has been created."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invitation.completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An Invitation has been completed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invitation.expired"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An Invitation has expired."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invitation.deleted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An Invitation has been canceled."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verification-events","__idx":11},"children":["Verification events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Verification events are issued during the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://help.checkr.com/hc/en-us/articles/217114247-Exceptions-Addressing-data-discrepancies-in-reports"},"children":["Exception"]}," process when a candidate is issued or has responded to a request to verify submitted PII."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The list of possible verification types that are in the webhook payload (verification_type inside the data object) can be found ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/reference#verification-types"},"children":["here"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["verification.created"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A verification is created and a request to upload a document or enter the data is forwarded to the candidate."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["verification.completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A document is uploaded or data is entered by the candidate."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["verification.processed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The data gathered by the verification is processed manually or automatically and a decision is made for the continuation of the background check."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When verifications are automatically processed, and do not require manual input, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["verification.processed"]}," webhook is sent immediately after the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["verification.completed"]}," webhook. These two webhooks may not arrive \"in order\"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"report-events","__idx":12},"children":["Report events"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"report.completed\",\n  \"data\": {\n    \"object\": {\n      \"id\": \"4722c07dd9a10c3985ae432a\",\n      \"status\": \"complete\",\n      \"result\": \"clear\",\n      \"package\": \"driver_pro\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.created"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A new Report has been created."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.updated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Report has been updated while the background check is run. This event is triggered on select update events, which include: ",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Report Estimated Completion Time changed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Drug Screening update status event created"]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.canceled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Report has been canceled."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.upgraded"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Report has been upgraded. Upgrades can be triggered either from an API call or from the Dashboard (\"Upgrade\" button). This is useful if you want to run a package (such as an MVR) and then upgrade it on completion (for example: add a County Criminal Search)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Report has been completed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.suspended"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Report has been suspended. Checkr is waiting for the candidate to provide additional documentation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.resumed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Report has resumed. (The candidate has provided documentation to a previously \"suspended\" Report.)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.paused"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Report has been paused. The report is awaiting a Review Action decision to continue or skip remaining screenings. For Enterprise Progressive reports, poll ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#operation/getReportProgressiveStatus"},"children":["Retrieve progressive checkpoint status"]}," to see which checkpoint is waiting."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.disputed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Report has been disputed by a candidate. Once a dispute has been completed, Checkr will trigger the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.dispute_completed"]}," webhook to communicate outcomes of the dispute."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.dispute_completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Dispute has been completed. The report object includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dispute_summary"]}," object with: ",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unresolved_disputes"]}," (boolean): whether any disputes remain unresolved"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["disputes"]},": array of dispute objects, each with:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (string): the dispute ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," (string): the dispute status"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["changes_made"]}," (boolean): whether the dispute resulted in changes to the report"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resolved_at"]}," (datetime): when the dispute was resolved"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.pre_adverse_action"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Pre-Adverse Action notice has been sent to the candidate of that report."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.post_adverse_action"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Post-Adverse Action notice has been sent to the candidate of that report."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.engaged"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Report has been adjudicated as \"engaged\". Use this event to track either all candidates you have officially engaged, or simply those candidates with a \"consider\" background check report that you have engaged. This can be triggered either from an API call or from the dashboard (\"Engage\" button)."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"adverse-action-events","__idx":13},"children":["Adverse Action events"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action.created"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A new Adverse Action has been created."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action.completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An Adverse Action has been completed. The post-adverse action notice has been sent."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action.paused"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An Adverse Action has been paused. The post-adverse action notice delivery has been temporarily halted."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action.resumed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A paused Adverse Action has been resumed. The post-adverse action notice will be rescheduled."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action.canceled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An Adverse Action has been canceled."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action.notice_not_delivered"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Adverse Action notice is confirmed to be undeliverable to the candidate of that report. User action is required."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"package-events","__idx":14},"children":["Package events"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package.created"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Package has been created."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package.updated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Package has been updated."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package.deleted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Package has been deleted."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"continuous-check-events","__idx":15},"children":["Continuous Check events"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["continuous_check.subscription_error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An error occurred when attempting to enroll a Candidate in Continuous MVR."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["continuous_check.confirmation_required"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Candidate has been unenrolled from Continuous MVR due to stale or invalid PII. The Candidate sumbitted updated information through the Checkr exception process. Action is required to re-enroll the Candidate."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"form-i-9-events","__idx":16},"children":["Form I-9 events"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["form_i9_v2.created"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A new Form I-9 has been created."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["form_i9_v2.updated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An in-progress Form I-9 has received an update. This usually means a change in status — for example, Section 1 being signed by a candidate, or a change in E-Verify status for a worksite with E-Verify enabled. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," You can find information about Form I-9 statuses in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#section/Reference/Form-I-9-definitions"},"children":["the Form I-9 reference section"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["form_i9_v2.completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Form I-9 has reached an authorized status."]}]}]}]}]}]},"headings":[{"value":"Webhooks","id":"webhooks","depth":1},{"value":"Webhook payload structure","id":"webhook-payload-structure","depth":2},{"value":"Attributes","id":"attributes","depth":2},{"value":"Supported webhook URL formats","id":"supported-webhook-url-formats","depth":2},{"value":"Responding to webhooks","id":"responding-to-webhooks","depth":2},{"value":"Order of events","id":"order-of-events","depth":2},{"value":"Securing webhooks","id":"securing-webhooks","depth":2},{"value":"Guarding against duplicate and missed report notifications","id":"guarding-against-duplicate-and-missed-report-notifications","depth":2},{"value":"Event types","id":"event-types","depth":2},{"value":"Candidate events","id":"candidate-events","depth":3},{"value":"Invitation events","id":"invitation-events","depth":3},{"value":"Verification events","id":"verification-events","depth":3},{"value":"Report events","id":"report-events","depth":3},{"value":"Adverse Action events","id":"adverse-action-events","depth":3},{"value":"Package events","id":"package-events","depth":3},{"value":"Continuous Check events","id":"continuous-check-events","depth":3},{"value":"Form I-9 events","id":"form-i-9-events","depth":3}],"frontmatter":{"title":"Webhooks","description":"Receive real-time updates on background check events via HTTP callbacks.","seo":{"title":"Webhooks"}},"lastModified":"2026-09-29T18:07:29.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}