{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Webhook Configuration","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhook-configuration","__idx":0},"children":["Webhook Configuration"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a Clearspeed assessment result is published, Clearspeed sends the result payload as an HTTP POST to a webhook URL you configure. This eliminates the need to poll for results — your system is notified in real time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each questionnaire has its own webhook URL configured independently from within the webapp."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page covers:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#configuring-your-webhook-url"},"children":["Configuring your webhook URL"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#securing-your-webhook-endpoint"},"children":["Securing your webhook endpoint"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#option-1--api-key"},"children":["Option 1 — API Key"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#option-2--client-credentials-oauth2"},"children":["Option 2 — Client Credentials (OAuth2)"]}]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#acknowledging-receipt"},"children":["Acknowledging receipt"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#retrying-failed-deliveries"},"children":["Retrying failed deliveries"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#webhook-payload"},"children":["Webhook payload"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuring-your-webhook-url","__idx":2},"children":["Configuring Your Webhook URL"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open the questionnaire in the Clearspeed web app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the questionnaire-specific left navigation bar, click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Integration"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook Integration"]}," section, enter your endpoint URL in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Web Hook URL"]}," field."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure the authentication method (see below)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/webhooks-step1-integration-page.d130798a977824c98df0e069f67367e2df9878929c1887ea8caef75f0e2e516e.9c1bb791.png","alt":"Integration page showing the Webhook Integration section with Web Hook URL field and Authentication Method button"},"children":[]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Screenshot placeholder — Integration page, Webhook Integration section"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your endpoint must be reachable from Clearspeed's servers over HTTPS. It does not need to be publicly exposed without authentication — Clearspeed will authenticate to your endpoint using the method you configure."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"securing-your-webhook-endpoint","__idx":3},"children":["Securing Your Webhook Endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Modify API Key Or Client Credentials"]}," to open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication Method"]}," dialog. Two options are available:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-1--api-key","__idx":4},"children":["Option 1 — API Key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API Key"]}," and enter the key value your endpoint expects. Clearspeed will include this value as a header on every webhook request, allowing your endpoint to verify the request is genuinely from Clearspeed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/webhooks-auth-apikey.8dbe1ca525cca6784e4d70c7499047d8315984509bcb9b6bf2066e2c5249ee43.9c1bb791.png","alt":"Authentication Method dialog with API Key option selected"},"children":[]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Screenshot placeholder — Authentication Method dialog, API Key selected"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-2--client-credentials-oauth2","__idx":5},"children":["Option 2 — Client Credentials (OAuth2)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client Credentials"]}," and provide the following values from your identity provider:"]},{"$$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":"strong","attributes":{},"children":["Token URL"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The OAuth2 token endpoint Clearspeed uses to obtain a bearer token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Audience"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The audience claim for the token (if required by your IdP)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client ID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The client ID issued by your IdP"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client Secret"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The client secret issued by your IdP"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Clearspeed will perform the client credentials flow before each delivery and send the resulting bearer token as an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <token>"]}," header with each webhook request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/webhooks-auth-client-credentials.099b6e4c94769c7c4a5193e964b01701afa822a42d6ac3e6c4bd8d698b02a3af.9c1bb791.png","alt":"Authentication Method dialog with Client Credentials option selected, showing Token URL, Audience, Client ID and Client Secret fields"},"children":[]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Screenshot placeholder — Authentication Method dialog, Client Credentials selected"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save"]}," to apply the configuration."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"acknowledging-receipt","__idx":6},"children":["Acknowledging Receipt"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your endpoint must return ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP 200"]}," to acknowledge successful receipt of the webhook payload. Any other status code (or a connection timeout) is treated as a delivery failure."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Clearspeed does not retry automatically on failure — see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#retrying-failed-deliveries"},"children":["Retrying failed deliveries"]}," below."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep your endpoint response fast. Perform any heavy processing asynchronously after returning 200."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retrying-failed-deliveries","__idx":7},"children":["Retrying Failed Deliveries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a webhook delivery fails (non-200 response or timeout), the original payload is stored. A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry Webhook"]}," button appears in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook Delivery Failed"]}," row on the Integration page — but only when there are failures from the past 15 days. If no recent failures exist, this row is not shown."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Clicking ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry Webhook"]}," resends all failed payloads from the past 15 days to your currently configured endpoint. Failures older than 15 days cannot be retried."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/webhooks-retry.9e2e6c713ce8a61827111633b3a41e1b26161487c6cb03cbbd5c15e6414b812f.9c1bb791.png","alt":"Integration page showing the Webhook Delivery Failed row with the Retry Webhook button"},"children":[]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Screenshot placeholder — Integration page, Retry Webhook button"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhook-payload","__idx":8},"children":["Webhook Payload"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Clearspeed sends a POST request with a JSON body. See the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/public/integration-api"},"children":["Integration API reference"]}," for the full payload schema and examples covering all result types (Result Published, Attempted - Incomplete, Attempted - Partial, Under Review, and Precision evaluations)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A representative payload looks like this:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"project_uuid\": \"fd9690b0-9050-4acd-ad74-7f906c07fe93\",\n  \"callback_type\": \"Result Update\",\n  \"interview_ref_num\": \"7858934895810\",\n  \"access_code\": \"71360059\",\n  \"status\": \"Result Published\",\n  \"overall_evaluation\": \"HR\",\n  \"summary\": \"HR\",\n  \"summary_bgcolor\": \"#dc3545\",\n  \"clear\": false,\n  \"is_admission\": false,\n  \"is_counter_measure\": false,\n  \"is_not_complete\": false,\n  \"participant_language\": \"English\",\n  \"questions_risk_rating\": [\n    { \"sequence\": \"1\", \"risk_level\": \"HR\", \"text\": \"Question 1\" },\n    { \"sequence\": \"2\", \"risk_level\": \"LR\", \"text\": \"Question 2\" }\n  ]\n}\n","lang":"json"},"children":[]}]},"headings":[{"value":"Webhook Configuration","id":"webhook-configuration","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Configuring Your Webhook URL","id":"configuring-your-webhook-url","depth":2},{"value":"Securing Your Webhook Endpoint","id":"securing-your-webhook-endpoint","depth":2},{"value":"Option 1 — API Key","id":"option-1--api-key","depth":3},{"value":"Option 2 — Client Credentials (OAuth2)","id":"option-2--client-credentials-oauth2","depth":3},{"value":"Acknowledging Receipt","id":"acknowledging-receipt","depth":2},{"value":"Retrying Failed Deliveries","id":"retrying-failed-deliveries","depth":2},{"value":"Webhook Payload","id":"webhook-payload","depth":2}],"frontmatter":{"title":"Webhook Configuration","description":"How to configure your webhook endpoint to receive Clearspeed result notifications, and how to secure it with an API key or OAuth2 client credentials.","seo":{"title":"Webhook Configuration"}},"lastModified":"2026-04-10T05:02:10.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}