professional work

TikTok Lead Generation Integration

OAuth and webhook pipeline for syncing leads from TikTok Business Center.

Full-Stack Developer · Undisclosed · Oct 2025 — Present

context

I needed to build a lead sync integration against TikTok's Marketing API v1.3. The documentation was sparse and there were real differences between sandbox and production that weren't clearly documented.

the challenge

In sandbox testing, advertiser validation was returning silent 401s with no explanation. Token exchange was also failing intermittently in sandbox but working fine in production.

approach

• 1.I treated every assumption about the API as wrong until I tested it. I read the full API reference instead of relying on the quickstart.
• 2.I stored sandbox/production config in the database per integration row instead of using environment variables alone. That made it easier to switch and test both modes.
• 3.I found that the sandbox advertiser validation uses a different endpoint from the OAuth flow, and that token exchange always uses the production base URL even in sandbox mode. Neither was documented clearly in the v1.3 reference.

technical highlights

• —Full OAuth 2.0 connect flow with token exchange, long-lived token storage, per-org integration rows, and admin-only sandbox mode.
• —Webhook lead sync with inline processing, idempotent upserts by source ID to prevent duplicates, and parallel processing per webhook call.
• —Every webhook call and its outcome is logged, so feed failures are diagnosable by query.
• —Supporting UI includes a per-form lead collection toggle, an Instant Form detail page showing synced leads, and an admin modal for switching environments.

result

Lead sync works for both bulk export and real-time webhook delivery. Sandbox and production are handled cleanly without environment-variable-only switching.

technologies