Setting Up Slack Integration

Learn how to configure Slack notifications for your PyQueryHub alerts using the official PyQueryHub Slack app and notification channels.

Overview

PyQueryHub integrates with Slack through the PyQueryHub Slack App that you install directly in your Slack workspace. Once configured, your alerts will automatically send notifications to your Slack channels when conditions are met.

Supported Alert Types

Data Alerts: Notify when query results meet specific conditions
Notebook Alerts: Send notifications from Python notebooks
Alert Resolution: Notify when alert conditions return to normal

Prerequisites

Before setting up Slack hooks, ensure you have:

✅ Active Subscription: Notification channels require a paid subscription
✅ Slack Admin Access: Permission to create incoming webhooks in your workspace
✅ PyQueryHub Alert: A configured alert that you want to send to Slack

Step 1: Install the PyQueryHub Slack App

1.1 Navigate to PyQueryHub Slack App

Go to the PyQueryHub Slack App Directory Page
Click "Add to Slack"
Sign in to your Slack workspace if prompted

1.2 Authorize the App

Select Workspace: Choose the Slack workspace where you want to install PyQueryHub
Review Permissions: The app will request permissions to:
- Send messages to channels
- Read channel information
- Access user information for mentions
Click "Allow" to grant permissions

1.3 Configure Default Channel

Select Default Channel: Choose where PyQueryHub notifications will be posted by default
Channel Options:
- Public channels: Any public channel in your workspace
- Private channels: Private channels you're a member of
- Direct messages: Send alerts via DM
Click "Install App" to complete installation

1.4 Invite the Bot (Optional)

For private channels or enhanced functionality:

Go to the Slack channel where you want notifications
Type /invite @PyQueryHub to add the bot to the channel
The bot will confirm it's been added and ready to send alerts

Step 2: Connect Your Slack Workspace to PyQueryHub

2.1 Access Slack Integration Settings

Navigate to Settings → Integrations → Slack
Click "Connect Slack Workspace"

2.2 Authenticate with Slack

OAuth Authorization: You'll be redirected to Slack for authentication
Select Workspace: Choose the workspace where you installed the PyQueryHub app
Confirm Connection: Click "Allow" to connect your workspace
Verification: You'll be redirected back to PyQueryHub with confirmation

2.3 Configure Notification Channels

After connecting your workspace:

Navigate to Settings → Notification Channels
Click "Add Channel"
Fill out the channel configuration:

Field	Value	Example
Alias	Friendly name for this channel	`"DevOps Alerts"`
Type	Select `Slack` from dropdown	`Slack`
Target	Select from your Slack channels	`#alerts-general`
Workspace	Your connected Slack workspace	`MyCompany Slack`

2.4 Save Configuration

Click "Create Channel" to save your Slack notification channel.

Step 3: Configure Alerts to Use Slack

3.1 Create or Edit Alert

Navigate to your Report → Alerts
Create new alert or edit existing one

3.2 Select Notification Channels

In the Channels section:

Select your Slack channel from the dropdown
Add multiple channels if needed (email, Slack, etc.)
Configure alert rules as needed

3.3 Save Alert

Click "Save Alert" to activate Slack notifications.

Slack Message Format

Alert Triggered Message

🚨 Alert Triggered: Daily Sales Alert

📊 Report: Q4 Sales Dashboard  
⚠️  Alert: Daily Sales Alert  
📅 When: Dec 15, 2024 2:14 PM

🔎 Broken Rules:
1. Revenue < 10000 (Current: 8750)
2. New Customers < 50 (Current: 23)

[View Report]

Alert Resolved Message

✅ Alert Resolved: Daily Sales Alert

📊 Report: Q4 Sales Dashboard
✅ This alert has returned to an 'ok' state.

Resolved: Dec 15, 2024 4:32 PM

[View Report]

Notebook Alert Message

📔 Notebook Alert: Data Processing Update

Status: Success ✅  
Message: Daily ETL completed successfully. 1,247 records processed.

[View Report]

Advanced Configuration

Multiple Slack Channels

You can create multiple Slack channels for different purposes:

Channel Name	Purpose	Webhook Target
`Critical Alerts`	High-priority issues	`#alerts-critical`
`Daily Reports`	Routine notifications	`#reports-daily`
`DevOps Alerts`	Infrastructure issues	`#devops-alerts`

Channel Organization

Best Practices:

Use descriptive aliases ("Sales Team Alerts" vs "Slack Channel 1")
Create separate channels for different alert priorities
Consider using different Slack channels for different teams

Troubleshooting

Common Issues

❌ "Slack workspace not connected"

Cause: PyQueryHub app not installed or OAuth connection expired
Solution: Reinstall the PyQueryHub Slack app and reconnect your workspace

❌ "Channel Access Restricted"

Cause: No active subscription or bot not invited to private channels
Solution: Upgrade to a paid plan and ensure bot is invited to target channels

❌ Messages not appearing in Slack

Cause: Bot may not have permissions, channel doesn't exist, or webhook revoked
Solution: Verify bot permissions, ensure target channel is accessible, check webhook validity

❌ HTTP 400 "invalid_payload" Error

Cause: Malformed JSON in webhook request or missing required fields
Solution: Check message formatting, ensure text or blocks field is present

❌ HTTP 403 "channel_is_archived" Error

Cause: Target channel has been archived in Slack
Solution: Unarchive the channel or update notification channel to active channel

❌ HTTP 404 "channel_not_found" Error

Cause: Channel was deleted or webhook lacks access permissions
Solution: Verify channel exists and recreate webhook if necessary

❌ HTTP 429 Rate Limit Exceeded

Cause: Sending messages faster than 1 per second
Solution: PyQueryHub automatically handles this with retry logic, no action needed

❌ "Alert not triggering"

Cause: Alert rules may not be met or Slack integration disconnected
Solution: Check alert conditions and verify Slack workspace connection status

❌ "Webhook URL revoked by Slack"

Cause: URL was accidentally exposed or detected as compromised
Solution: Create a new webhook URL and update PyQueryHub notification channel

Testing Your Configuration

Create Test Alert: Set up a simple alert that will definitely trigger
Use Low Threshold: Set alert conditions you can easily meet for testing
Check Slack Channel: Verify messages appear with correct formatting
Test Bot Commands: Try mentioning @PyQueryHub in channels to test responsiveness
Test Resolution: Ensure resolution messages work when conditions improve

Getting Help

If you encounter issues:

Verify the PyQueryHub app is properly installed in your Slack workspace
Check Slack workspace permissions and bot channel access
Ensure your PyQueryHub subscription includes notification channels
Test webhook URLs manually to verify they're working correctly
Check Slack workspace audit logs for any app permission changes
Contact support with specific error messages and workspace details

Security Considerations

OAuth App Security

🔐 App Permissions: The PyQueryHub Slack app only requests necessary permissions for messaging
🔄 Token Management: OAuth tokens are securely managed and can be revoked from Slack workspace settings
👥 Workspace Control: Slack workspace administrators can manage app installations and permissions
📝 Audit Trail: All app installations and permissions are logged in Slack's workspace audit logs

Integration Security

🔐 Encrypted Transmission: All messages sent to Slack use HTTPS encryption
🛡️ Token Validation: Slack validates all incoming webhook requests for authenticity
🚫 URL Revocation: Slack automatically revokes webhook URLs if they're detected as compromised
📊 Rate Limiting: Slack enforces rate limits to prevent spam and abuse

Data Privacy

🔒 Sensitive Data: Be mindful of what data appears in alert messages
🏢 Internal Channels: Use private Slack channels for confidential alerts
📋 Compliance: Ensure Slack integration meets your organization's compliance requirements

Examples

E-commerce Sales Alert

Scenario: Alert when daily revenue drops below target

Alert Configuration:
  Name: "Daily Revenue Alert"
  Channel: "Sales Team Slack"
  Rules: 
    - Revenue < 50000
  Frequency: Daily at 6 PM

Slack Message:

🚨 Alert Triggered: Daily Revenue Alert

📊 Report: Daily Sales Dashboard
⚠️  Alert: Daily Revenue Alert  
📅 When: Dec 15, 2024 6:00 PM

🔎 Broken Rules:
1. Revenue < 50000 (Current: 42,750)

[View Report]

System Health Monitoring

Scenario: Monitor database performance metrics

Alert Configuration:
  Name: "DB Performance Alert"  
  Channel: "DevOps Slack"
  Rules:
    - Query Response Time > 2000ms
    - Active Connections > 100

Marketing Campaign Tracking

Scenario: Track conversion rates for campaigns

Alert Configuration:
  Name: "Low Conversion Alert"
  Channel: "Marketing Team Slack"  
  Rules:
    - Conversion Rate < 2.5%
    - Cost per Acquisition >

Best Practices

1. Channel Naming

✅ Use descriptive, consistent names
✅ Include team/purpose in the name
✅ Example: "Sales Team - Revenue Alerts"

2. Alert Frequency

⏰ Avoid spam: Don't set alerts too frequently
📅 Business hours: Consider when your team checks Slack
🔕 Quiet hours: Respect team schedules for non-critical alerts

3. Message Clarity

📊 Context: Include report names and links
🔢 Specific values: Show actual vs expected values
⚡ Actionable: Make it clear what needs attention

4. Team Coordination

👥 Assign ownership: Make it clear who should respond to alerts
📋 Document procedures: Create runbooks for common alert scenarios
🔄 Review regularly: Audit and update alert configurations

Alternative: Custom Webhook Integration

If your organization requires a custom webhook approach instead of the PyQueryHub Slack app:

Step-by-Step Webhook Setup

1. Create a Slack App

Go to Slack API and click "Create New App"
Choose "From scratch"
Enter App Name: "PyQueryHub Notifications"
Select your Slack workspace
Click "Create App"

2. Enable Incoming Webhooks

In your app settings, navigate to "Incoming Webhooks"
Toggle "Activate Incoming Webhooks" to On
Click "Add New Webhook to Workspace"
Select the target channel where notifications will be posted
Click "Allow" to authorize the webhook

3. Copy Webhook URL

After authorization, you'll receive a webhook URL like:

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

Important: Keep this URL secure and never share it publicly.

4. Configure in PyQueryHub

Navigate to Settings → Notification Channels
Click "Add Channel"
Enter channel details:
- Alias: "Custom Slack Alerts"
- Type: "Slack"
- Target: Paste your webhook URL
Click "Create Channel"

Advanced Webhook Configuration

Technical Specifications

HTTP Request Format:

Method: POST
Content-Type: application/json
URL Format: https://hooks.slack.com/services/T{WORKSPACE_ID}/B{BOT_ID}/X{VERIFICATION_TOKEN}

Basic Message Payload:

{
    "text": "🚨 Alert Triggered: Daily Sales Alert",
    "blocks": [
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "*Report:* Q4 Sales Dashboard\n*Alert:* Daily Revenue Alert"
            }
        }
    ]
}

Message Formatting

PyQueryHub automatically formats messages with:

Rich text formatting using Slack's markdown syntax (mrkdwn)
Block Kit layouts with sections, dividers, and fields
Interactive elements like buttons for report links
Status indicators with emojis and color coding
Maximum 100 attachments per message (Slack limit)

Error Handling & Response Codes

Our webhook integration handles all Slack HTTP response codes:

Success Responses:

200 OK: Message posted successfully

Client Error Responses:

400 Bad Request:
- invalid_payload: Malformed JSON or missing required fields
- no_text: Message lacks both text and blocks content
- too_many_attachments: Exceeded 100 attachment limit
403 Forbidden:
- channel_is_archived: Target channel has been archived
- action_prohibited: Insufficient permissions
404 Not Found:
- channel_not_found: Channel doesn't exist or bot lacks access
410 Gone:
- channel_is_archived: Channel permanently archived

Server Error Responses:

500 Internal Server Error: Slack service issues
503 Service Unavailable: Temporary Slack downtime

Rate Limiting

Standard Rate Limit: 1 message per second per webhook
Burst Capability: Short bursts allowed, then throttled
429 Response: Returned when rate limit exceeded
Retry Logic: PyQueryHub automatically retries with exponential backoff

Security Features

URL Security:

Webhook URLs are unique secrets - treat like passwords
Format: https://hooks.slack.com/services/T{WORKSPACE}/B{BOT}/X{TOKEN}
Automatic Revocation: Slack actively scans for exposed URLs and revokes them
No Recovery: Once revoked, webhook URLs cannot be restored (must create new ones)

PyQueryHub Security Measures:

Encrypted Storage: Webhook URLs are encrypted in our database using AES-256
Automatic Detection: If Slack revokes a webhook, we immediately notify administrators
Access Control: Only workspace administrators can configure webhook channels
Audit Logging: All webhook configuration changes are logged with timestamps and user details
Connection Testing: Webhook validity is tested before saving configuration

Webhook Limitations (by design):

Cannot override the configured channel, username, or icon
Cannot delete messages once posted to Slack
No message history - webhooks are one-way communication
No interactive responses - cannot receive user input from Slack

When to Use Custom Webhooks

Enterprise Security: Your organization restricts third-party app installations
Custom Control: You need full control over message formatting and delivery
Legacy Systems: Integration with existing webhook infrastructure
Compliance Requirements: Your organization requires webhook-based integrations

Note: While custom webhooks provide more control, the PyQueryHub Slack app offers better user experience, automatic channel discovery, and enhanced security through OAuth.

Need help with advanced configurations or having issues? Check our troubleshooting guide or contact support.

Overview

Get Started

Reports

Integrations

Setting Up Slack Integration

Overview

Supported Alert Types

Prerequisites

Step 1: Install the PyQueryHub Slack App

1.1 Navigate to PyQueryHub Slack App

1.2 Authorize the App

1.3 Configure Default Channel

1.4 Invite the Bot (Optional)

Step 2: Connect Your Slack Workspace to PyQueryHub

2.1 Access Slack Integration Settings

2.2 Authenticate with Slack

2.3 Configure Notification Channels

2.4 Save Configuration

Step 3: Configure Alerts to Use Slack

3.1 Create or Edit Alert

3.2 Select Notification Channels

3.3 Save Alert

Slack Message Format

Alert Triggered Message

Alert Resolved Message

Notebook Alert Message

Advanced Configuration

Multiple Slack Channels

Channel Organization

Troubleshooting

Common Issues

Testing Your Configuration

Getting Help

Security Considerations

OAuth App Security

Integration Security

Data Privacy

Examples

E-commerce Sales Alert

System Health Monitoring

Marketing Campaign Tracking

Best Practices

1. Channel Naming

2. Alert Frequency

3. Message Clarity

4. Team Coordination

Alternative: Custom Webhook Integration

Step-by-Step Webhook Setup

1. Create a Slack App

2. Enable Incoming Webhooks

3. Copy Webhook URL

4. Configure in PyQueryHub

Advanced Webhook Configuration

Technical Specifications

Message Formatting

Error Handling & Response Codes

Rate Limiting

Security Features

When to Use Custom Webhooks