# Configuring Socure's Workforce Verification Solution via Webhooks This guide walks Ashby customers through configuring Socure's workforce verification solution via webhooks in Ashby. All you must do is configure webhooks in Ashby. RiskOS™ then automatically initiates a workforce verification workflow and applies a tag (for example, `HIGH_RISK_IDENTITY` or `LOW_RISK_IDENTITY`) to the candidate profile in Ashby. [RiskOS™ Case Management](https://help.socure.com/riskos/docs/case-management-overview) provides all the insights including model scores, reason codes, and Gen AI powered explanations to explain the "why" behind the decision. ## Configure webhooks for Top of Funnel Passive Checks (5 Minutes) Retrieve your **Customer ID** from the Developer Workbench in RiskOS™. - Set the **Webhook type** to **Application Submitted** - Enter the **Request URL** - Enter the **Secret Token** - Enable the webhook ## Configure webhooks for Bottom of Funnel Document Verification (5 Minutes) Retrieve your **Customer ID** from the Developer Workbench in RiskOS™. - Set the **Webhook Type** to **Candidate Hired** - Enter the **Request URL** - Enter the **Secret Token** - Enable the webhook ## Configure Ashby to capture candidate consent or other legal requirements (5 Minutes) Use a required question for any necessary legal language or links to documents (e.g., a candidate privacy policy) or to collect any required consents for workforce verification. For example, you may require a user to answer "I Consent" before submission. *Consult your legal team for any specific requirements.* ## Before you start configuration Make sure the following setup steps are complete: | Step | Details | |-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| | RiskOS™ Account | Your RiskOS™ account is provisioned and the `workforce_verification` workflow is enabled. Your Socure Solutions Consultant can confirm. | | Review workflow | Review your workflow and adjust risk thresholds as needed. The `workforce_verification` workflow includes the following modules by default: Email Risk + Graph Intelligence, Phone Risk + Graph Intelligence, Sigma Identity Fraud + Graph Intelligence, Sigma Synthetic Fraud, Document Verification. You can add additional modules and adjust risk thresholds as needed. | ## How it works with Ashby 1. Configure an Application Submitted webhook in Ashby to trigger passive checks in RiskOS™. 2. RiskOS™ retrieves the following information from Ashby: Name (this is subsequently parsed as First Name and Last Name), Primary Phone Number, Primary Email, Physical Address (if available), IP Address. 3. RiskOS™ feeds the candidate information to a pre-configured workflow using Socure products such as Phone Risk, Email Risk, Sigma Identity Fraud, Sigma Synthetic Fraud, Graph Intelligence. 4. RiskOS™ evaluation includes model scores, reason codes and graph intelligence signals, which are fed into a decisioning logic, which drive one of two pre-configured tag values: `HIGH_RISK_IDENTITY` or `LOW_RISK_IDENTITY`. 5. RiskOS™ applies the tag to the applicant profile in Ashby (e.g., `HIGH_RISK_IDENTITY`, `LOW_RISK_IDENTITY`). 6. Configure a Candidate Hired webhook for document verification at the bottom of the funnel. 7. RiskOS™ applies final document verification tags (`DOCUMENT_VERIFICATION_PASSED`, `DOCUMENT_VERIFICATION_FAILED`, `DOCUMENT_VERIFICATION_REVIEW`). ### Example workflow ``` HRRiskOS™AshbyHRRiskOS™AshbyApplication Submitted webhookRun Workforce Verification workflowApply HIGH_RISK_IDENTITY or LOW_RISK_IDENTITY tagReview flagged casesCandidate Hired webhookRun Document Verification workflowApply final verification tag ``` ## Configuring Ashby webhooks > 📘 > > **Note**: > > Before you start, contact [support@socure.com](mailto:support@socure.com) to: > 1. Get a **Request URL** and **Secret Token** from Socure. You will use this to configure webhooks in Ashby. > 2. Share your **Ashby API key** with Socure. This is required to complete the configuration. ### Application Submitted webhook (Top-of-Funnel Passive Checks) 1. Sign in to Ashby as an Administrator. 2. Navigate: **Admin > Integrations > Webhooks**. 3. Click **\+ New** to add a webhook and configure as follows: | Field | Value | |--------------|-------------------------------------------------------------------------------------------------------| | Webhook Type | Application Submitted | | Request URL | `https://hooks.riskos.socure.com/ashby-partner-init?accountId=` | | Secret Token | Your secret token | | Auth Type | None | | Enabled | True (checked) | > customerId` is available in your RiskOS™ account under **Developer Workbench → API Keys**. - You will now see the **Application Submitted** webhook on the **Webhooks** page. Once configured, RiskOS™ appends tags (`HIGH_RISK_IDENTITY` or `LOW_RISK_IDENTITY`) to the applicant profile. ### Candidate Hired webhook (Bottom-of-Funnel Document Verification) Follow the same configuration steps as the **Application Submitted webhook** section to add a second webhook with **Webhook Type: Candidate Hired**. RiskOS™ appends tags such as: - `DOCUMENT_VERIFICATION_PASSED` - `DOCUMENT_VERIFICATION_FAILED` - `DOCUMENT_VERIFICATION_REVIEW` ## Case review in RiskOS™ RiskOS™ offers a [case management solution](https://help.socure.com/riskos/docs/case-management-overview) for flagged candidates. Review includes: - Tags and decision logic - Reason codes and model scores - Gen AI explanations of risk signals This helps your HR team understand why a candidate was flagged and supports compliance/audit readiness. ## Best practices for integration and maintenance - Validate webhook configurations and test with sample applicants. - Use RiskOS™ sandbox mode for safe testing before production rollout. - Escalate issues with `eval_id`, webhook payload, and context to Socure Support. - Log applicant evaluations, decision tags, and errors for auditability. ## Validation checklist ### Webhook events Application Submitted triggers RiskOS™ checks Candidate Hired triggers document verification ### Schema + error handling Request URLs and secrets are correct Webhook retries are supported in case of network issues ### Logging + observability Ashby and RiskOS™ logs capture full payloads Correlation IDs included Sensitive data redacted ## Next steps Once webhooks are configured, test the integration by submitting a test application or hiring a test candidate in Ashby. Confirm RiskOS™ applies the expected tags (`HIGH_RISK_IDENTITY`, `DOCUMENT_VERIFICATION_PASSED`, etc.). RiskOS™ also adds a note to the candidate profile with a deep link to the RiskOS™ case. HR team members can click the link (for example, [https://riskos.socure.com/cases/detail/workforce_verification/a581f613-fe4b-4842-ad34-81157b23a6e7](https://riskos.socure.com/cases/detail/workforce_verification/a581f613-fe4b-4842-ad34-81157b23a6e7)) to access the case details in RiskOS™ Case Management. > 📘 > > **Note**: > > Add the HR team member as a RiskOS™ user from the [Users](https://help.socure.com/riskos/docs/manage-users) page. RiskOS™ Case Management empowers reviewers and analysts to make confident decisions about the cases they investigate. Each case provides detailed insights including model scores, reason codes, and workflow decisions. GenAI Explainability adds natural-language explanations to key outputs across Socure's platform, surfacing the "why" behind risk scores, identity match decisions, and document verification results. Updated 3 days ago