Sync Notion with GitHub Projects Without Losing Your Mind

Your Notion database has 2,000 tasks with custom fields like "Priority 🚀" and "Status (Updated)". Your GitHub project has completely different status names and no custom fields. Someone just renamed "Priority 🚀" to "Urgency Level" and broke everything.

Welcome to integration hell - where two perfectly functional systems become a nightmare when you try to connect them.

Why Webhooks Are Fucking Liars

Webhooks don't work. Period. That's the first thing you need to know. Notion says "real-time" - they mean "whenever we feel like it, maybe 30 seconds, probably never." GitHub's are worse - they just stop firing and don't tell you why.

Spent three days wondering why nothing was syncing before I realized their webhook endpoint was returning 404s and nobody bothered logging it.

Here's what will ruin your week (ask me how I know):

Webhook Listeners (That Mostly Don't Work)

• GitHub webhooks fire inconsistently when their servers are under load (they don't tell you this)
• Notion webhooks randomly stop working and you won't know until someone complains
• You'll need ngrok for testing because localhost webhooks are fantasy. Works fine on Linux, randomly explodes on Windows 11 with WSL2 for reasons that make no sense (something about network adapter conflicts)
• Pro tip: Always implement webhook signature verification or script kiddies will spam your endpoints with garbage
• ngrok tunnels die randomly and you won't notice until everything's broken for 20 minutes

2. Data Mapping That Doesn't Corrupt Everything

• Notion's "Person" field becomes a GitHub username - except when it doesn't because email matching fails
• Date fields use different timezones and ISO 8601 formats that will fuck you over
• Custom fields in GitHub Projects have weird restrictions Notion doesn't care about
• Status mapping breaks when someone adds "In Review 🔥" as a status

3. API Clients That Actually Work

• Notion's REST API rate limits you at 3 requests/second average (no burst allowance despite what people think)
• GitHub's GraphQL API costs more points than you think - that simple query just ate 50 points
• Both APIs lie about their error messages - "Bad Request" tells you nothing useful about what you actually fucked up
• You need the official Notion SDK because hand-rolling HTTP requests is masochism, but their SDK has weird peer dependency conflicts with newer Node versions
• Updated one npm package last month and suddenly nothing works. Turns out Notion's SDK doesn't play nice with Express 5.x. Spent 4 hours debugging before rolling back to Express 4.x like a caveman

4. State Tracking So You Don't Create Infinite Loops

Found out about infinite loops the hard way. Forgot to add a sync_source field and watched one status change create hundreds of duplicate tickets. GitHub started rate limiting us, Notion started throwing errors, and our Slack channel exploded.

Add sync_source and last_synced_at fields or watch everything burn. Redis works for tracking sync state, but we're still getting random sync loops about once a month and nobody knows why. Circuit breakers helped when Notion went down, but sometimes they trip for no reason and stay tripped.

Log everything because you'll be debugging this shit at 3am with Linda from product asking why her tickets are wrong again.

What Actually Happens in Production

The integration works perfectly until sprint planning day. Then:

• Someone bulk-updates 200 tickets in Notion
• Your webhook endpoint gets hammered with requests
• GitHub's API starts throwing 429 errors
• Half the updates fail and now your data is inconsistent
• The PM starts asking why their tickets are wrong
• You question all your life choices

If you're lucky, changes sync in under 10 seconds. If you're unlucky, you restart everything and pray to the webhook gods.

Built this for our team because manually syncing tickets was driving everyone insane. Now we have an automated system that breaks in different ways every month, but at least our PM stops yelling at us about inconsistent ticket statuses.

Still breaks regularly. Sometimes webhooks just stop and we restart everything and pray. But it beats manual updates.

Don't build this. Seriously. But if you're going to ignore me anyway (and let's be honest, you probably will because developers are stubborn idiots who think they can do it better), here's what actually breaks and why most solutions don't work.

The next thing you'll try is third-party tools because building custom seems scary. That's cute. Let me tell you why those will disappoint you too.

Security is important, sure. But first you need to get the damn thing working without your tokens getting revoked every 3 days.

Token Management: Why I Want to Throw Tokens in a Fire

Notion Tokens Are Fucking Liars

Internal integration tokens supposedly don't expire, but they get revoked randomly when someone leaves the workspace. Found this out when everything broke on a Friday and the only error was "401 Unauthorized" - super helpful for debugging at 2am.

Set up workspace permissions correctly or Linda from marketing will accidentally break everything when she loses access. We still don't know why tokens sometimes work and sometimes don't - probably some internal Notion magic we'll never understand.

GitHub Personal Access Tokens Are a Security Nightmare

• Classic PATs have org-wide access by default - way too permissive
• Fine-grained tokens only work with specific repos and expire in 1 year max (GitHub forces expiration, no way around it)
• Token scopes are confusing as fuck - repo includes way more than you think
• If the token owner leaves the company, everything breaks silently

What Actually Works in Production

Use GitHub Apps, Not Personal Tokens

• GitHub Apps let you install once per org instead of per user
• They get their own identity so they don't break when people leave
• Installation tokens auto-refresh, saving you from token rotation hell
• Downside: Way more complex to set up initially

Store Secrets Properly or Get Fired

• Don't put tokens in environment variables on your laptop - use dotenv files in .gitignore
• AWS Secrets Manager costs $0.40/month per secret but saves your ass
• HashiCorp Vault is overkill unless you're Netflix
• Whatever you do, don't commit tokens to git - GitGuardian will find them and shame you

Webhook Security (Because Script Kiddies Exist)

Verify Webhook Signatures or Get Owned

// GitHub signature verification
const crypto = require('crypto');
const signature = req.headers['x-hub-signature-256'];
const payload = JSON.stringify(req.body);
const expected = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(payload)
  .digest('hex');

if (signature !== `sha256=${expected}`) {
  throw new Error('Invalid signature');
}

Notion Webhooks Are Less Secure

• They only verify via shared secret in headers
• No HMAC verification like GitHub
• Rate limit your webhook endpoints because attackers will spam them
• Use express-rate-limit with Redis backing

The Compliance Nightmare

GDPR Compliance Means Asking Permission

• You need explicit consent to sync personal data between platforms
• Right to be forgotten means building data deletion workflows
• Document exactly what data flows where for Data Protection Impact Assessments
• This is why most companies just buy Unito instead

SOC 2 Audit Trail Requirements

• Log every API call with timestamps and user context
• Store logs for at least 1 year (longer if you're in healthcare)
• Immutable logging with AWS CloudTrail or similar
• Your auditors will ask for specific log queries - build them ahead of time

Real-World Failure Modes

What Goes Wrong at 3am:

• Webhook secrets rotate and nobody updates the code
• GitHub organization permissions change and break your app installation
• Notion workspace admin removes your integration without warning
• Rate limiting kicks in during bulk operations and everything fails
• Someone runs a security scan and flags your webhook endpoint as suspicious

Took about two weeks to get basic functionality working. Then spent another 3 months fixing edge cases I never thought of, like what happens when someone deletes a GitHub repo mid-sync (spoiler: everything explodes). Plan for this to take 3x longer than you think, then add another month for security stuff you forgot about.

Test token expiration. Found this out when everything broke on a Friday afternoon - service account token expired with zero notification.

Shit We Never Figured Out

• Random failure rate on webhook signature verification - same payload, same secret, sometimes just returns false for no reason we can figure out
• Notion workspace permissions randomly reset themselves about once every 6 months
• GitHub App installations sometimes lose repo access for no reason
• Memory leak somewhere in the auth flow that requires restarts every few weeks

Even with "perfect" auth, this integration breaks in ways that make no sense. You'll be debugging auth failures at 3am while questioning why you didn't just become a farmer.

At least now you know why your webhooks are going to start failing mysteriously. Speaking of mysterious failures, let me walk you through all the ways this will break at the worst possible moment.