Connecting JobCannon to SmartRecruiters

JobCannon integrates with SmartRecruiters via OAuth 2.0 and webhook events. SmartRecruiters is a recruiting platform trusted by enterprise organizations and staffing firms. This guide covers credential provisioning, sandbox testing, and production deployment.

Quick Reference

Prerequisites

Step 1: Create an Integration in SmartRecruiters

1. **Log in to SmartRecruiters** as Company Admin

2. **Navigate:** Settings → Integrations → Connected Applications

3. **Click "Create Integration"** or "Add Custom App"

4. **Fill in the form:**

- Name: JobCannon Assessments

- Description: JobCannon assessment delivery and scoring platform

- Redirect URI: https://api.jobcannon.io/smartrecruiters/oauth-callback

- Scopes:

- `candidates:read` (read candidate data)

- `candidates:write` (update candidate records)

- `assessments:read` (read assessment metadata)

- `assessments:write` (post results)

- `custom_fields:read` (access custom scorecard fields)

5. **Click "Create"** — SmartRecruiters generates Client ID and Client Secret

Step 2: Configure Webhook Subscriptions

In the integration settings, subscribe to these events:

POST https://api.smartrecruiters.com/v1/webhooks/subscriptions

Authorization: Bearer [access-token]

Content-Type: application/json

{

"event": "candidate.assessment.completed",

"targetUrl": "https://api.jobcannon.io/smartrecruiters/webhooks",

"headers": {

"X-Custom-Header": "JobCannon"

}

}

SmartRecruiters will deliver webhook events to this URL for all assessment completions.

Step 3: Request Credentials from JobCannon

Email [email protected] with:

JobCannon will initiate OAuth 2.0 authorization flow. You (Company Admin) will approve the scopes, and JobCannon receives a refresh token valid for 2 years.

Step 4: Configure Assessment Catalog

Once authorized, you can assign JobCannon assessments:

1. **Open a job** in SmartRecruiters

2. **Go to Pipeline → [Stage]**

3. **Click "Add Action"** → Assessment

4. **Select JobCannon** from the assessment provider list

5. **Choose a test** (Big Five, DISC, EQ, etc.)

6. **Configure:**

- Required or optional

- Trigger: auto-advance or manual

- Due date (default: 7 days)

- Email template (branded or default)

7. **Save**

Step 5: Test in Sandbox

Before production:

1. **Create a test candidate** in SmartRecruiters sandbox

2. **Advance to the assessment stage**

3. **Trigger the assessment** (auto or manual)

4. **Candidate receives email** with assessment link

5. **Complete the assessment** in browser

6. **Verify webhook delivery:** Check JobCannon admin (/admin/integrations/smartrecruiters/logs)

7. **Check SmartRecruiters:** Scorecard should update with result

Common Errors

Error: "Invalid OAuth redirect URI"

**Cause:** Registered URI doesn't match the callback URL.

**Fix:**

1. Verify SmartRecruiters shows https://api.jobcannon.io/smartrecruiters/oauth-callback

2. Check for typos or trailing slashes

3. Regenerate integration if needed

Error: "Webhook signature validation failed"

**Cause:** HMAC signature is missing or incorrect.

**Fix:**

1. Verify SmartRecruiters sends `X-SmartRecruiters-Signature` header

2. Confirm webhook secret matches the value in integration settings

3. Verify payload is not modified before signature validation

Error: "Assessment delivery failed (403 Forbidden)"

**Cause:** OAuth scopes don't include `assessments:write`.

**Fix:**

1. Check integration scopes in SmartRecruiters

2. If missing, re-authorize and approve all required scopes

3. Retry assessment delivery

Verification Checklist

Rate Limits

SmartRecruiters allows 100 requests per second with no stated burst limit. Implement rate limiting on your side to avoid throttling.

Data Residency

JobCannon stores assessment result metadata in EU region (Supabase) for GDPR compliance. SmartRecruiters stores candidate records in your configured region (US or EU). Webhook payloads are encrypted in transit (HTTPS TLS 1.2+).

---

**Vendor docs:** https://developers.smartrecruiters.com/reference

**Webhooks:** https://developers.smartrecruiters.com/reference/webhooks

**Support:** [email protected]