{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Webhooks"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhooks","__idx":0},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks let you receive lifecycle events from Checkr Tenant in near-real-time"," ","instead of polling the API. When a subscribed event happens, Checkr Tenant"," ","sends an HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," to the URL you registered, with a JSON payload"," ","describing the event."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"available-events","__idx":1},"children":["Available events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All webhook events are listed below. More will be added over time and your endpoints will start receiving new event types automatically. Design your handler to ignore events it doesn't recognize."]},{"$$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":"Fires when"},"children":["Fires when"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.applicant.visited"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The applicant visits the apply link for an order at any time before they complete the application."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.applicant.started"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The applicant consents to and starts the screening application."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.applicant.completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The applicant finishes and submits the application."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.product.completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A product finishes processing and results are available on the report."]}]},{"$$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":["An order has finished processing and the full report is available."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"registering-an-endpoint","__idx":2},"children":["Registering an endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhook endpoints are managed from the"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://tenant.checkr.com/settings/developer"},"children":["Developer settings"]}," page in your"," ","dashboard. Each endpoint is scoped to a single organization and receives every"," ","event your organization emits — there is no per-event filtering yet."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you create a webhook you also receive a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["signing secret"]},", used to"," ","verify incoming requests. Save it somewhere durable — it is shown once at"," ","creation time and cannot be retrieved later."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"url-requirements","__idx":3},"children":["URL requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your endpoint URL must:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTPS"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Be reachable from the public internet. URLs pointing at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["localhost"]},","," ","private networks, or other internal addresses are rejected."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"live-vs-test-mode","__idx":4},"children":["Live vs. test mode"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each webhook is registered in either ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["live"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["test"]}," mode, and only"," ","receives events for resources that match its mode:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Live"]}," — receives events for live (production) resources."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test"]}," — receives events for test-mode resources only."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This lets you exercise your webhook handler end-to-end against test-mode"," ","resources before pointing real production traffic at it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"testing-connectivity","__idx":5},"children":["Testing connectivity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test"]}," action on the dashboard to send a bare connectivity probe"," ","to your URL — a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," with no body and no signature. Your endpoint should"," ","respond with any 2xx status to indicate it is reachable. The probe is not a"," ","real event delivery and is not retried."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delivery","__idx":6},"children":["Delivery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each delivery is an HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," from Checkr Tenant to the URL you registered:"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Method"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["User-Agent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckrTenant/1"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Tenant-Signature"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Signature header (see below)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A delivery is considered successful when your endpoint responds with a 2xx"," ","status code. Anything else — non-2xx responses, network errors, or timeouts"," ","— is treated as a failure and retried with exponential backoff. Your endpoint"," ","should be ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["idempotent"]},": the same event id may be delivered more than once."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"event-payload","__idx":7},"children":["Event payload"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every webhook request body has the same envelope:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"evt_K9dM2pXqR4vN8tLZbWyHJa\",\n  \"object\": \"event\",\n  \"type\": \"report.completed\",\n  \"created_at\": \"2026-04-29T17:42:13Z\",\n  \"data\": {\n    \"id\": \"rp_F3hQ7wEsLp2xBnVcRuMyTk\",\n    \"order_id\": \"ord_WHImYp5RjqUxBowWilloQ\"\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":"Field"},"children":["Field"]},{"$$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":["Unique event id (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["evt_…"]},"). Stable across retries — use it for idempotency on your side."]}]},{"$$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":["Always ",{"$$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":["Event type (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.completed"]},"). See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#available-events"},"children":["Available events"]},"."]}]},{"$$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":["UTC timestamp the event was created, in ISO-8601 format. Use this for ordering — delivery order is not guaranteed."]}]},{"$$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":["Event-specific payload. Shape varies by event type — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#data-shape-per-event"},"children":["Data shape per event"]}," below."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"data-shape-per-event","__idx":8},"children":["Data shape per event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The shape of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," depends on the event type:"]},{"$$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":"data fields"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," fields"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.applicant.visited"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (applicant id), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order_id"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.applicant.started"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (applicant id), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order_id"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.applicant.completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (applicant id), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order_id"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.product.completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (product result id), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product"]}," (snake case product name e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["criminal_history"]},")"]}]},{"$$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":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (report id), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order_id"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For report events fetch the full report from"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/v1#operation/get-report"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /reports/{id}"]}]}," when you need its"," ","contents."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verifying-signatures","__idx":9},"children":["Verifying signatures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every delivery includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Tenant-Signature"]}," header so you can verify the"," ","request came from Checkr Tenant and was not modified in transit:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Tenant-Signature: t=1714414933,v1=8d2b...c4f1\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1"]}," is the hex-encoded HMAC-SHA256 of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<t>.<raw_request_body>"]},", computed"," ","with your endpoint's signing secret as the key. Recompute it on your side"," ","and compare against ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1"]}," using a constant-time comparison. Read the raw"," ","request body ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["before any JSON parsing"]}," — re-serialization changes the"," ","bytes you HMAC."]}]},"headings":[{"value":"Webhooks","id":"webhooks","depth":2},{"value":"Available events","id":"available-events","depth":3},{"value":"Registering an endpoint","id":"registering-an-endpoint","depth":3},{"value":"URL requirements","id":"url-requirements","depth":4},{"value":"Live vs. test mode","id":"live-vs-test-mode","depth":4},{"value":"Testing connectivity","id":"testing-connectivity","depth":4},{"value":"Delivery","id":"delivery","depth":3},{"value":"Event payload","id":"event-payload","depth":3},{"value":"Data shape per event","id":"data-shape-per-event","depth":4},{"value":"Verifying signatures","id":"verifying-signatures","depth":3}],"frontmatter":{"seo":{"title":"Webhooks"}},"lastModified":"2026-06-18T19:17:15.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}