Connecting JobCannon to Workable

JobCannon integrates with Workable via OAuth 2.0 and the Assessment API. Workable is a recruiting platform trusted by mid-market and enterprise companies. This guide covers credential provisioning, sandbox testing, and production deployment.

Quick Reference

Prerequisites

Step 1: Create an Integration in Workable

1. **Log in to Workable** as admin

2. **Navigate:** Settings → Developer Tools → API & Integrations → Applications

3. **Click "Create Application"**

4. **Fill in the form:**

- Name: JobCannon Assessments

- Description: JobCannon assessment delivery and scoring

- Callback URL: https://api.jobcannon.io/workable/oauth-callback

- Scopes:

- `candidates` (read candidate data)

- `candidate_assessments` (create and update assessments)

- `jobs` (read job metadata)

- `evaluation_forms` (read/write evaluation forms)

5. **Click "Create"** — Workable will generate a Client ID and Client Secret

Step 2: Store Credentials Securely

Store these credentials in a secrets manager (AWS Secrets Manager, Vercel env, etc.):

Step 3: Initiate OAuth Authorization

Email [email protected] with:

JobCannon will initiate the OAuth 2.0 flow. You (workspace admin) will be redirected to approve the scopes. After approval, JobCannon receives an authorization code and exchanges it for an access token (refresh token valid for 2 years).

Step 4: Configure Assessment Delivery

Once authorized, JobCannon will integrate with Workable's Assessment API. You can now:

1. **Open a job** in Workable

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

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

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

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

6. **Configure:**

- Required or optional

- Send timing: auto-advance or manual

- Due date (default: 7 days)

7. **Save**

Step 5: Test in Staging

Before production:

1. **Create a candidate** in Workable staging environment

2. **Advance to the assessment stage**

3. **Complete the assessment** via the email link

4. **Verify webhook delivery:** Check JobCannon admin (/admin/integrations/workable/logs)

5. **Check Workable:** Evaluation form should appear on the candidate record

Common Errors

Error: "Invalid OAuth redirect URI"

**Cause:** Callback URL doesn't match the registered value.

**Fix:**

1. Verify Workable shows https://api.jobcannon.io/workable/oauth-callback

2. Check for typos or trailing slashes

3. Regenerate the application if needed

Error: "Insufficient scope: candidate_assessments"

**Cause:** The scopes in the application don't include `candidate_assessments`.

**Fix:**

1. Edit the application in Workable

2. Add `candidate_assessments` scope

3. Re-authorize in JobCannon

Error: "429 Too Many Requests"

**Cause:** Rate limit exceeded (60 requests/minute).

**Fix:**

1. Implement exponential backoff (5s → 15s → 60s)

2. Batch requests where possible

3. Contact support if you need higher limits

Verification Checklist

Rate Limits

Workable allows 60 requests per minute with burst tolerance to 120 requests/min. Implement backoff when receiving 429 status codes.

---

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

**Assessment API:** https://developers.workable.com/reference/candidate-assessments

**Support:** [email protected]