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:

- Look for popup blocker icon in browser URL bar - Click and allow popups for Brief - Try connecting again

1. Check popup blocker

- 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

1. Verify permissions

- Wait a few minutes - Clear browser cache - Try in an incognito/private window

1. Try again

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	Instant (webhook)
PostHog	1-2 minutes

- Go to Integrations page in Brief - Look for sync status indicator - If "Error", try disconnecting and reconnecting

1. Check integration status

- Check that the connected tool has recent activity - For Linear: Ensure issues exist from last 90 days - For GitHub: Ensure repo has recent PRs or commits

1. Verify data exists

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:

- Go to Integrations page - Click "Sync Now" next to the integration

1. Trigger manual sync

- Disconnect the integration - Wait 30 seconds - Reconnect it

1. Reconnect

OAuth Issues

Why does it say "Access Denied" during OAuth?

OAuth flow shows "Access denied" or permission error.

Fixes:

- Ensure you have admin/owner permissions in the tool - For GitHub orgs: Need org admin or owner role - For Atlassian: May need workspace admin

1. Verify admin access

- Some orgs block third-party apps by default - GitHub: Check org settings → Third-party access - Atlassian: Check admin console → App management

1. Check app restrictions

- For Atlassian tools, ask your workspace admin to approve Brief - Send them the Brief app page to review

1. Request approval

What should I do if popups are blocked?

Nothing happens when clicking "Connect".

Fixes:

- Browser shows popup blocker icon in URL bar - Click it and select "Always allow popups from briefhq.ai" - Click "Connect" again

1. Allow popups

- Some browsers are more aggressive with popups - Try Chrome or Firefox if using Safari

1. Try different browser

Webhook Issues

Why aren't my webhooks firing?

Initial sync worked but new changes don't appear.

Fixes:

- For Linear: Settings → Webhooks → Look for Brief webhook - For GitHub: Repo → Settings → Webhooks → Look for Brief webhook

1. Check webhook registration

- Webhook URL should include your org ID - Format: https://app.briefhq.ai/api/webhooks/{tool}?org_id=YOUR_ORG_ID

1. Verify webhook URL

- Disconnect in Brief - Wait 30 seconds - Reconnect (this re-registers webhooks)

1. Reconnect integration

Why does Fireflies show "Invalid signature" error?

"Invalid signature" error in Fireflies integration.

Fixes:

- Go to Fireflies → Settings → Developer - After saving webhook, copy the secret shown - Paste it EXACTLY into Brief (no extra spaces) - Save in Brief

1. Re-copy webhook secret

- In Fireflies, disable webhook - Save - Re-enable webhook - Copy new secret - Update in Brief

1. Regenerate webhook

Tool-Specific Issues

Linear

"No issues synced"

• Ensure Linear workspace has issues created in last 90 days
• 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 Manage next to the GitHub integration. 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:

- Which integration - What you tried - Screenshot of error (if any) - Your org ID (from Settings)

1. Check status — Visit status.briefhq.ai for service status
2. Contact support — Email hello@briefhq.ai with:

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	Instant	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