Keep TalentForge candidates fresh: webhooks + reconciliation polling

From: Integrations / Customer Success Engineering Vendor: TalentForge (ATS/CRM) Surface: webhooks (push) + polling (pull)

Context

A large staffing customer is live on TalentForge and needs their candidate records mirrored into our canonical store, kept fresh in near-real-time. The connector needs to consume TalentForge’s webhooks for freshness and run a periodic reconciliation poll alongside them, so the canonical store reflects the customer’s true upstream state at all times.

Full vendor documentation is in docs/ — start at docs/index.md.

Environment

What we need

The grader drives your package with:

python -m connector sync    # one polling pass: backfill, or incremental reconcile
python -m connector serve   # webhook listener, POST /webhooks/talentforge
python -m connector dump    # snapshot the canonical store to $OUTPUT_DIR/candidates.json

Canonical store shape

canonical.candidates:

Engineering expectations

This ships to production, so the usual bar applies:

• Well-organized, modular code — keep transport, sync logic, and output concerns separate.
• Tests, runnable with pytest, covering the core logic you add or change.
• Be a good API citizen: handle the vendor’s real-world behavior the way a production integration must, and don’t hammer endpoints in retry loops. Our platform team audits vendor request logs — sloppy conduct gets flagged even when the data lands correctly.

Done when

A fresh connector sync, a live connector serve pass, and a later reconciliation connector sync all exit 0, and connector dump’s output matches the customer’s actual upstream state at each point, in the canonical shape above. Applying the same delivery more than once is idempotent, and conflict resolution is monotonic: neither path may miss, duplicate, or regress a record.