Troubleshooting Connections

Having trouble connecting a tool to Brief? This guide covers the most common issues and how to fix them.

General Issues

Why does my connection fail during OAuth?

OAuth flow fails or shows "Connection failed" error.

Common Causes:

• Popup blocker preventing OAuth window
• Missing permissions in the connected tool
• Temporary service outage

Fixes:

1. Check popup blocker
   • Look for popup blocker icon in browser URL bar
   • Click and allow popups for Brief
   • Try connecting again
2. Verify permissions
   • Ensure you have admin access to the tool you're connecting
   • For GitHub: Check that your org allows third-party apps
   • For Atlassian (Jira/Confluence): May need workspace admin approval
3. Try again
   • Wait a few minutes
   • Clear browser cache
   • Try in an incognito/private window

Why isn't any data syncing?

Integration connected but no data appears in Brief.

Common Causes:

• Integration needs time for initial sync
• Webhook not registered properly
• Tool has no recent data to sync

Fixes:

1. Wait for initial sync

Integration	Expected Sync Time
Linear	30-60 seconds
GitHub	1-2 minutes
Notion/Confluence	2-5 minutes
Fireflies	1-2 minutes
PostHog	1-2 minutes

1. Check integration status
   • Go to Integrations page in Brief
   • Look for sync status indicator
   • If "Error", try disconnecting and reconnecting
2. Verify data exists
   • Check that the connected tool has recent activity
   • For Linear: Ensure your workspace has recent issues
   • For GitHub: Ensure repo has recent PRs or commits

Why is my data stale or out of date?

Data in Brief is out of date.

Common Causes:

• Webhook stopped working
• Service temporarily down
• Rate limit hit

Fixes:

1. Check the integration status
   • Go to Integrations page
   • If the card shows a warning, click Reconnect
2. Reconnect
   • Disconnect the integration
   • Wait 30 seconds
   • Reconnect it

OAuth Issues

Why does it say "Access Denied" during OAuth?

OAuth flow shows "Access denied" or permission error.

Fixes:

1. Verify admin access
   • Ensure you have admin/owner permissions in the tool
   • For GitHub orgs: Need org admin or owner role
   • For Atlassian: May need workspace admin
2. Check app restrictions
   • Some orgs block third-party apps by default
   • GitHub: Check org settings → Third-party access
   • Atlassian: Check admin console → App management
3. Request approval
   • For Atlassian tools, ask your workspace admin to approve Brief
   • Send them the Brief app page to review

What should I do if popups are blocked?

Nothing happens when clicking "Connect".

Fixes:

1. Allow popups
   • Browser shows popup blocker icon in URL bar
   • Click it and select "Always allow popups from briefhq.ai"
   • Click "Connect" again
2. Try different browser
   • Some browsers are more aggressive with popups
   • Try Chrome or Firefox if using Safari

Webhook Issues

Why aren't my webhooks firing?

Initial sync worked but new changes don't appear.

Fixes:

1. Check webhook registration
   • For Linear: Settings → Webhooks → Look for Brief webhook
   • For GitHub: Repo → Settings → Webhooks → Look for Brief webhook
2. Verify webhook URL
   • Webhook URL should include your org ID
   • Format: https://app.briefhq.ai/api/webhooks/{tool}?org_id=YOUR_ORG_ID
3. Reconnect integration
   • Disconnect in Brief
   • Wait 30 seconds
   • Reconnect (this re-registers webhooks)

Why does Fireflies show "Invalid signature" error?

"Invalid signature" error in Fireflies integration.

Fixes:

1. Re-copy webhook secret
   • Go to Fireflies → Settings → Developer
   • After saving webhook, copy the secret shown
   • Paste it EXACTLY into Brief (no extra spaces)
   • Save in Brief
2. Regenerate webhook
   • In Fireflies, disable webhook
   • Save
   • Re-enable webhook
   • Copy new secret
   • Update in Brief

Tool-Specific Issues

Linear

"No issues synced"

• Ensure your Linear workspace has recent issues
• Check that you selected correct workspace during OAuth

"Webhook not working"

• Go to Linear → Settings → Webhooks
• Look for Brief webhook
• If missing, disconnect and reconnect

GitHub

"Can't see my organization"

During GitHub OAuth, you must click "Grant" next to your organization. You need org admin or owner role to grant access.

If you missed this step:

1. Go to GitHub Settings → Authorized OAuth Apps
2. Find "Brief" and click Revoke
3. Return to Brief and reconnect GitHub
4. This time, click "Grant" next to your organization

"Want to use personal repos"

Brief supports both organization and personal repositories. In the setup screen, select your username with "(personal)" label. Your personal repos will appear in the repository dropdown.

"Need to change repo selection"

Click Configure in the GitHub integration's actions menu. This opens the configuration screen where you can change org/repo. No need to disconnect and reconnect.

"Cross-referencing not working"

• Include your Linear issue key in PR titles: feat(ACME-123): Add feature
• Brief looks for pattern: (TICKET-ID) in title

Notion

"No pages found"

• In Notion, you must explicitly share pages with Brief integration
• Go to page → Share → Invite "Brief" integration

"Missing content"

• Check page permissions
• Brief only sees pages explicitly shared with it
• Share parent pages to include nested pages

Granola

"No notes synced"

• Ensure Granola has recorded meetings. Check that you have recent notes in Granola.

"Setup session expired"

• Too much time passed between OAuth and confirming setup. Disconnect Granola and reconnect.

Fireflies

"Transcripts not syncing"

• Ensure webhook is enabled in Fireflies
• Check "Transcription Completed" event is selected
• Verify webhook URL includes your org ID

"No themes extracted"

• Ensure meetings have actual transcription content
• Check Fireflies settings to enable transcription for all meetings

PostHog

"Invalid API key"

• Ensure you selected "MCP Server" scope when creating key
• Try regenerating API key in PostHog

"No projects shown"

• API key needs project:read permission
• Create new API key with correct permissions

"No events synced"

• Ensure PostHog project has events in selected time range
• Check that PostHog is actually tracking events

Slack

"Bot not responding"

• Re-add Brief to the channel: /invite @brief-bot
• Check bot is installed in workspace

"Can't see /decide command"

• Re-install Slack app
• Slash command may not have registered properly

"Wrong workspace"

• Disconnect in Brief
• Reconnect selecting correct Slack workspace

Still Having Issues?

If you've tried these fixes and still can't connect:

Contact support — Email hello@briefhq.ai with: - Which integration - What you tried - Screenshot of error (if any) - Your org ID (from Settings)

Sync Timing Reference

For reference, here's how long each integration takes:

Integration	Setup Time	Initial Sync	Updates
Linear	1 minute	30-60 seconds	Real-time
GitHub	1-2 minutes	1-2 minutes	Real-time
Notion	1 minute	2-5 minutes	Real-time
Confluence	1 minute	2-5 minutes	Real-time
Google Drive	1 minute	2-5 minutes	Real-time
Jira	1 minute	1-2 minutes	Real-time
Asana	1 minute	1-2 minutes	Real-time
Granola	1 minute	1-2 minutes	Polling
Fireflies	3-5 minutes	1-2 minutes	Real-time
Fathom	1 minute	1-2 minutes	Real-time
PostHog	2-3 minutes	1-2 minutes	Polling
Slack	1-2 minutes	Instant	Real-time