Connecting JobCannon to Ashby

JobCannon integrates with Ashby via OAuth 2.0 authentication and webhooks. Ashby is an API-first recruiting platform designed for technical hiring teams. This guide walks you through credential setup, sandbox testing, and production deployment.

Quick Reference

Prerequisites

Step 1: Create an Integration in Ashby

1. **Log in to Ashby** as workspace admin

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

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

4. **Fill in the form:**

- Name: JobCannon Assessments

- Description: JobCannon assessment delivery and scoring

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

- Scopes required:

- `candidate:write` (update candidate scorecard)

- `candidate:read` (fetch candidate metadata)

- `webhook:write` (register webhooks)

- `assessment:read` (read assessment results)

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

Step 2: Configure OAuth Redirect Endpoints

In the integration settings, specify:

Step 3: Request an OAuth Token from JobCannon

Email [email protected] with:

JobCannon will initiate the OAuth 2.0 authorization flow. You (workspace admin) will approve the scopes, and JobCannon will receive a refresh token valid for 2 years.

Step 4: Configure Webhooks

Once OAuth is authorized, JobCannon will register two webhooks on your Ashby workspace:

1. **candidate.created** — Triggered when a new candidate is added (used for logging)

2. **assessment.completed** — Triggered when a candidate completes a JobCannon assessment

Ashby will deliver payloads to: https://api.jobcannon.io/ashby/webhooks

Step 5: Test in Sandbox

Before going live:

1. **Create a test candidate** in Ashby (Settings → Sandbox Candidates)

2. **Trigger a JobCannon assessment** via the candidate profile

3. **Complete the assessment** in a browser

4. **Verify webhook delivery:** Check your JobCannon admin logs at /admin/integrations/ashby/logs

5. **Confirm scorecard update:** The candidate's scorecard should show the assessment result

Common Errors

Error: "Invalid OAuth scope"

**Cause:** One or more requested scopes are not available on your workspace tier.

**Fix:**

1. Check Ashby workspace plan (some scopes require Enterprise tier)

2. Verify scope list matches Ashby API documentation

3. Email [email protected] if a scope is missing

Error: "Webhook signature validation failed"

**Cause:** Webhook payload was tampered or signature header is missing.

**Fix:**

1. Verify Ashby sends HMAC-SHA256 signature in `X-Ashby-Webhook-Signature` header

2. Confirm Client Secret is used correctly to compute the signature

3. Check webhook delivery logs in Ashby admin → Webhooks → Event Logs

Error: "401 Unauthorized when updating candidate scorecard"

**Cause:** OAuth token expired or has insufficient scopes.

**Fix:**

1. Check token expiry (refresh if >1.5 years old)

2. Verify scopes include `candidate:write`

3. Re-authorize the integration in Ashby settings

Verification Checklist

Rate Limits

Ashby allows 100 requests per second with burst tolerance up to 1,000 requests/sec. If you exceed sustained rates, Ashby will return 429 (Too Many Requests). JobCannon implements exponential backoff: 5s → 15s → 60s → 5m.

Data Residency

By default, assessment data is stored in Ashby's US region (AWS us-east-1). JobCannon stores result metadata in EU region (Supabase) for GDPR compliance. Webhook payloads are encrypted in transit (HTTPS TLS 1.2+).

---

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

**Webhook spec:** https://developers.ashbyhq.com/reference/webhooks

**Support:** [email protected]