Configuration de l'Intégration Slack

Apprenez à configurer les notifications Slack pour vos alertes PyQueryHub en utilisant l'application officielle PyQueryHub Slack et les canaux de notification.

Aperçu

PyQueryHub s'intègre à Slack via l'Application PyQueryHub Slack que vous installez directement dans votre espace de travail Slack. Une fois configurée, vos alertes enverront automatiquement des notifications à vos canaux Slack lorsque les conditions sont remplies.

Types d'Alertes Pris en Charge

Alertes de Données : Notifier lorsque les résultats de requête remplissent des conditions spécifiques
Alertes de Notebooks : Envoyer des notifications depuis les notebooks Python
Résolution d'Alertes : Notifier lorsque les conditions d'alerte reviennent à la normale

Prérequis

Avant de configurer les hooks Slack, assurez-vous d'avoir :

✅ Abonnement Actif : Les canaux de notification nécessitent un abonnement payant
✅ Accès Admin Slack : Permission de créer des webhooks entrants dans votre espace de travail
✅ Alerte PyQueryHub : Une alerte configurée que vous souhaitez envoyer à Slack

Étape 1 : Installer l'Application PyQueryHub Slack

1.1 Naviguer vers l'Application PyQueryHub Slack

Allez sur la Page du Répertoire d'Applications PyQueryHub Slack
Cliquez sur "Ajouter à Slack"
Connectez-vous à votre espace de travail Slack si demandé

1.2 Autoriser l'Application

Sélectionner l'Espace de Travail : Choisissez l'espace de travail Slack où vous voulez installer PyQueryHub
Examiner les Permissions : L'application demandera les permissions pour :
- Envoyer des messages aux canaux
- Lire les informations du canal
- Accéder aux informations utilisateur pour les mentions
Cliquez sur "Autoriser" pour accorder les permissions

1.3 Configurer le Canal par Défaut

Sélectionner le Canal par Défaut : Choisissez où les notifications PyQueryHub seront publiées par défaut
Options de Canal :
- Canaux publics : N'importe quel canal public dans votre espace de travail
- Canaux privés : Canaux privés dont vous êtes membre
- Messages directs : Envoyer des alertes via DM
Cliquez sur "Installer l'Application" pour terminer l'installation

1.4 Inviter le Bot (Optionnel)

Pour les canaux privés ou une fonctionnalité améliorée :

Allez sur le canal Slack où vous voulez des notifications
Tapez /invite @PyQueryHub pour ajouter le bot au canal
Le bot confirmera qu'il a été ajouté et est prêt à envoyer des alertes

Étape 2 : Connecter Votre Espace de Travail Slack à PyQueryHub

2.1 Accéder aux Paramètres d'Intégration Slack

Naviguez vers Paramètres → Intégrations → Slack
Cliquez sur "Connecter l'Espace de Travail Slack"

2.2 S'Authentifier avec Slack

Autorisation OAuth : Vous serez redirigé vers Slack pour l'authentification
Sélectionner l'Espace de Travail : Choisissez l'espace de travail où vous avez installé l'application PyQueryHub
Confirmer la Connexion : Cliquez sur "Autoriser" pour connecter votre espace de travail
Vérification : Vous serez redirigé vers PyQueryHub avec confirmation

2.3 Configurer les Canaux de Notification

Après avoir connecté votre espace de travail :

Naviguez vers Paramètres → Canaux de Notification
Cliquez sur "Ajouter un Canal"
Remplissez la configuration du canal :

Champ	Valeur	Exemple
Alias	Nom convivial pour ce canal	`"Alertes DevOps"`
Type	Sélectionnez `Slack` dans le menu déroulant	`Slack`
Cible	Sélectionnez parmi vos canaux Slack	`#alertes-general`
Espace de Travail	Votre espace de travail Slack connecté	`MonEntreprise Slack`

2.4 Enregistrer la Configuration

Cliquez sur "Créer le Canal" pour enregistrer votre canal de notification Slack.

Étape 3 : Configurer les Alertes pour Utiliser Slack

3.1 Créer ou Modifier une Alerte

Naviguez vers votre Rapport → Alertes
Créez une nouvelle alerte ou modifiez-en une existante

3.2 Sélectionner les Canaux de Notification

Dans la section Canaux :

Sélectionnez votre canal Slack dans le menu déroulant
Ajoutez plusieurs canaux si nécessaire (email, Slack, etc.)
Configurez les règles d'alerte selon vos besoins

3.3 Enregistrer l'Alerte

Cliquez sur "Enregistrer l'Alerte" pour activer les notifications Slack.

Format des Messages Slack

Message d'Alerte Déclenchée

🚨 Alerte Déclenchée : Alerte Quotidienne des Ventes

📊 Rapport : Tableau de Bord des Ventes T4  
⚠️  Alerte : Alerte Quotidienne des Ventes  
📅 Quand : 15 déc 2024 14:14

🔎 Règles Enfreintes :
1. Revenus < 10000 (Actuel : 8750)
2. Nouveaux Clients < 50 (Actuel : 23)

[Voir le Rapport]

Message d'Alerte Résolue

✅ Alerte Résolue : Alerte Quotidienne des Ventes

📊 Rapport : Tableau de Bord des Ventes T4
✅ Cette alerte est revenue à un état 'normal'.

Résolue : 15 déc 2024 16:32

[Voir le Rapport]

Message d'Alerte de Notebook

📔 Alerte de Notebook : Mise à Jour du Traitement des Données

Statut : Succès ✅  
Message : ETL quotidien terminé avec succès. 1 247 enregistrements traités.

[Voir le Rapport]

Configuration Avancée

Plusieurs Canaux Slack

Vous pouvez créer plusieurs canaux Slack pour différents usages :

Nom du Canal	Objectif	Cible du Webhook
`Alertes Critiques`	Problèmes à haute priorité	`#alertes-critiques`
`Rapports Quotidiens`	Notifications de routine	`#rapports-quotidiens`
`Alertes DevOps`	Problèmes d'infrastructure	`#alertes-devops`

Organisation des Canaux

Meilleures Pratiques :

Utilisez des alias descriptifs ("Alertes Équipe des Ventes" vs "Canal Slack 1")
Créez des canaux séparés pour différentes priorités d'alerte
Considérez l'utilisation de différents canaux Slack pour différentes équipes

Dépannage

Problèmes Courants

❌ "Espace de travail Slack non connecté"

Cause : Application PyQueryHub non installée ou connexion OAuth expirée
Solution : Réinstallez l'application PyQueryHub Slack et reconnectez votre espace de travail

❌ "Accès au Canal Restreint"

Cause : Aucun abonnement actif ou bot non invité dans les canaux privés
Solution : Passez à un plan payant et assurez-vous que le bot est invité dans les canaux cibles

❌ Les messages n'apparaissent pas dans Slack

Cause : Le bot peut ne pas avoir les permissions, le canal n'existe pas, ou le webhook est révoqué
Solution : Vérifiez les permissions du bot, assurez-vous que le canal cible est accessible, vérifiez la validité du webhook

❌ Erreur HTTP 400 "invalid_payload"

Cause : JSON mal formé dans la requête webhook ou champs requis manquants
Solution : Vérifiez le formatage du message, assurez-vous que le champ text ou blocks est présent

❌ Erreur HTTP 403 "channel_is_archived"

Cause : Le canal cible a été archivé dans Slack
Solution : Désarchivez le canal ou mettez à jour le canal de notification vers un canal actif

❌ Erreur HTTP 404 "channel_not_found"

Cause : Le canal a été supprimé ou le webhook n'a pas les permissions d'accès
Solution : Vérifiez que le canal existe et recréez le webhook si nécessaire

❌ HTTP 429 Limite de Taux Dépassée

Cause : Envoi de messages plus rapide qu'1 par seconde
Solution : PyQueryHub gère cela automatiquement avec une logique de réessai, aucune action nécessaire

❌ "L'alerte ne se déclenche pas"

Cause : Les règles d'alerte peuvent ne pas être remplies ou l'intégration Slack est déconnectée
Solution : Vérifiez les conditions d'alerte et l'état de connexion de l'espace de travail Slack

❌ "URL de webhook révoquée par Slack"

Cause : L'URL a été accidentellement exposée ou détectée comme compromise
Solution : Créez une nouvelle URL de webhook et mettez à jour le canal de notification PyQueryHub

Tester Votre Configuration

Créer une Alerte de Test : Configurez une alerte simple qui se déclenchera certainement
Utiliser un Seuil Bas : Définissez des conditions d'alerte que vous pouvez facilement atteindre pour tester
Vérifier le Canal Slack : Vérifiez que les messages apparaissent avec le bon formatage
Tester les Commandes du Bot : Essayez de mentionner @PyQueryHub dans les canaux pour tester la réactivité
Tester la Résolution : Assurez-vous que les messages de résolution fonctionnent lorsque les conditions s'améliorent

Obtenir de l'Aide

Si vous rencontrez des problèmes :

Vérifiez que l'application PyQueryHub est correctement installée dans votre espace de travail Slack
Vérifiez les permissions de l'espace de travail Slack et l'accès du bot au canal
Assurez-vous que votre abonnement PyQueryHub inclut les canaux de notification
Testez les URLs de webhook manuellement pour vérifier qu'elles fonctionnent correctement
Vérifiez les journaux d'audit de l'espace de travail Slack pour tout changement de permissions d'application
Contactez le support avec des messages d'erreur spécifiques et les détails de l'espace de travail

Considérations de Sécurité

Sécurité de l'Application OAuth

🔐 Permissions de l'Application : L'application PyQueryHub Slack ne demande que les permissions nécessaires pour la messagerie
🔄 Gestion des Jetons : Les jetons OAuth sont gérés en toute sécurité et peuvent être révoqués depuis les paramètres de l'espace de travail Slack
👥 Contrôle de l'Espace de Travail : Les administrateurs de l'espace de travail Slack peuvent gérer les installations et permissions d'applications
📝 Piste d'Audit : Toutes les installations et permissions d'applications sont enregistrées dans les journaux d'audit de l'espace de travail Slack

Sécurité de l'Intégration

🔐 Transmission Chiffrée : Tous les messages envoyés à Slack utilisent le chiffrement HTTPS
🛡️ Validation des Jetons : Slack valide toutes les requêtes webhook entrantes pour l'authenticité
🚫 Révocation d'URL : Slack révoque automatiquement les URLs de webhook si elles sont détectées comme compromises
📊 Limitation de Taux : Slack applique des limites de taux pour prévenir le spam et les abus

Confidentialité des Données

🔒 Données Sensibles : Soyez attentif aux données qui apparaissent dans les messages d'alerte
🏢 Canaux Internes : Utilisez des canaux Slack privés pour les alertes confidentielles
📋 Conformité : Assurez-vous que l'intégration Slack répond aux exigences de conformité de votre organisation

Exemples

Alerte de Ventes E-commerce

Scénario : Alerte lorsque les revenus quotidiens tombent en dessous de l'objectif

Configuration d'Alerte :
  Nom : "Alerte de Revenus Quotidiens"
  Canal : "Slack Équipe des Ventes"
  Règles : 
    - Revenus < 50000
  Fréquence : Quotidienne à 18h

Message Slack :

🚨 Alerte Déclenchée : Alerte de Revenus Quotidiens

📊 Rapport : Tableau de Bord des Ventes Quotidiennes
⚠️  Alerte : Alerte de Revenus Quotidiens  
📅 Quand : 15 déc 2024 18:00

🔎 Règles Enfreintes :
1. Revenus < 50000 (Actuel : 42 750)

[Voir le Rapport]

Surveillance de la Santé du Système

Scénario : Surveiller les métriques de performance de la base de données

Configuration d'Alerte :
  Nom : "Alerte de Performance BD"  
  Canal : "Slack DevOps"
  Règles :
    - Temps de Réponse de Requête > 2000ms
    - Connexions Actives > 100

Suivi de Campagne Marketing

Scénario : Suivre les taux de conversion pour les campagnes

Configuration d'Alerte :
  Nom : "Alerte de Faible Conversion"
  Canal : "Slack Équipe Marketing"  
  Règles :
    - Taux de Conversion < 2.5%
    - Coût par Acquisition > 50$

Meilleures Pratiques

1. Nommage des Canaux

✅ Utilisez des noms descriptifs et cohérents
✅ Incluez l'équipe/l'objectif dans le nom
✅ Exemple : "Équipe des Ventes - Alertes de Revenus"

2. Fréquence des Alertes

⏰ Évitez le spam : Ne définissez pas des alertes trop fréquentes
📅 Heures de bureau : Considérez quand votre équipe vérifie Slack
🔕 Heures calmes : Respectez les horaires de l'équipe pour les alertes non critiques

3. Clarté des Messages

📊 Contexte : Incluez les noms et liens des rapports
🔢 Valeurs spécifiques : Montrez les valeurs réelles vs attendues
⚡ Actionnable : Indiquez clairement ce qui nécessite une attention

4. Coordination d'Équipe

👥 Assigner la propriété : Indiquez clairement qui doit répondre aux alertes
📋 Documenter les procédures : Créez des guides de procédures pour les scénarios d'alerte courants
🔄 Réviser régulièrement : Auditez et mettez à jour les configurations d'alerte

Alternative : Intégration de Webhook Personnalisée

Si votre organisation nécessite une approche webhook personnalisée au lieu de l'application PyQueryHub Slack :

Configuration Étape par Étape du Webhook

1. Créer une Application Slack

Allez sur Slack API et cliquez sur "Créer une Nouvelle Application"
Choisissez "Depuis zéro"
Entrez Nom de l'Application : "Notifications PyQueryHub"
Sélectionnez votre espace de travail Slack
Cliquez sur "Créer l'Application"

2. Activer les Webhooks Entrants

Dans les paramètres de votre application, naviguez vers "Webhooks Entrants"
Basculez "Activer les Webhooks Entrants" sur Activé
Cliquez sur "Ajouter un Nouveau Webhook à l'Espace de Travail"
Sélectionnez le canal cible où les notifications seront publiées
Cliquez sur "Autoriser" pour autoriser le webhook

3. Copier l'URL du Webhook

Après autorisation, vous recevrez une URL de webhook comme :

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

Important : Gardez cette URL sécurisée et ne la partagez jamais publiquement.

4. Configurer dans PyQueryHub

Naviguez vers Paramètres → Canaux de Notification
Cliquez sur "Ajouter un Canal"
Entrez les détails du canal :
- Alias : "Alertes Slack Personnalisées"
- Type : "Slack"
- Cible : Collez votre URL de webhook
Cliquez sur "Créer le Canal"

Configuration Avancée du Webhook

Spécifications Techniques

Format de Requête HTTP :

Méthode : POST
Content-Type : application/json
Format d'URL : https://hooks.slack.com/services/T{ID_ESPACE_TRAVAIL}/B{ID_BOT}/X{JETON_VERIFICATION}

Charge Utile de Message de Base :

{
    "text": "🚨 Alerte Déclenchée : Alerte Quotidienne des Ventes",
    "blocks": [
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "*Rapport :* Tableau de Bord des Ventes T4\n*Alerte :* Alerte de Revenus Quotidiens"
            }
        }
    ]
}

Formatage des Messages

PyQueryHub formate automatiquement les messages avec :

Formatage de texte enrichi en utilisant la syntaxe markdown de Slack (mrkdwn)
Mises en page Block Kit avec sections, diviseurs et champs
Éléments interactifs comme des boutons pour les liens de rapports
Indicateurs de statut avec emojis et codage couleur
Maximum 100 pièces jointes par message (limite Slack)

Gestion des Erreurs et Codes de Réponse

Notre intégration webhook gère tous les codes de réponse HTTP de Slack :

Réponses de Succès :

200 OK : Message publié avec succès

Réponses d'Erreur Client :

400 Bad Request :
- invalid_payload : JSON mal formé ou champs requis manquants
- no_text : Le message manque de contenu text et blocks
- too_many_attachments : Limite de 100 pièces jointes dépassée
403 Forbidden :
- channel_is_archived : Le canal cible a été archivé
- action_prohibited : Permissions insuffisantes
404 Not Found :
- channel_not_found : Le canal n'existe pas ou le bot n'a pas accès
410 Gone :
- channel_is_archived : Canal archivé de façon permanente

Réponses d'Erreur Serveur :

500 Internal Server Error : Problèmes de service Slack
503 Service Unavailable : Indisponibilité temporaire de Slack

Limitation de Taux

Limite de Taux Standard : 1 message par seconde par webhook
Capacité de Rafale : Courtes rafales autorisées, puis limitées
Réponse 429 : Retournée lorsque la limite de taux est dépassée
Logique de Réessai : PyQueryHub réessaie automatiquement avec un recul exponentiel

Fonctionnalités de Sécurité

Sécurité des URLs :

Les URLs de webhook sont des secrets uniques - traitez-les comme des mots de passe
Format : https://hooks.slack.com/services/T{ESPACE_TRAVAIL}/B{BOT}/X{JETON}
Révocation Automatique : Slack scanne activement les URLs exposées et les révoque
Pas de Récupération : Une fois révoquées, les URLs de webhook ne peuvent pas être restaurées (il faut en créer de nouvelles)

Mesures de Sécurité PyQueryHub :

Stockage Chiffré : Les URLs de webhook sont chiffrées dans notre base de données en utilisant AES-256
Détection Automatique : Si Slack révoque un webhook, nous notifions immédiatement les administrateurs
Contrôle d'Accès : Seuls les administrateurs de l'espace de travail peuvent configurer les canaux webhook
Journalisation d'Audit : Tous les changements de configuration webhook sont enregistrés avec horodatage et détails de l'utilisateur
Test de Connexion : La validité du webhook est testée avant d'enregistrer la configuration

Limitations du Webhook (par conception) :

Ne peut pas remplacer le canal, nom d'utilisateur ou icône configurés
Ne peut pas supprimer les messages une fois publiés sur Slack
Pas d'historique de messages - les webhooks sont une communication unidirectionnelle
Pas de réponses interactives - ne peut pas recevoir d'entrée utilisateur depuis Slack

Quand Utiliser des Webhooks Personnalisés

Sécurité d'Entreprise : Votre organisation restreint les installations d'applications tierces
Contrôle Personnalisé : Vous avez besoin d'un contrôle total sur le formatage et la livraison des messages
Systèmes Hérités : Intégration avec une infrastructure webhook existante
Exigences de Conformité : Votre organisation exige des intégrations basées sur des webhooks

Note : Bien que les webhooks personnalisés offrent plus de contrôle, l'application PyQueryHub Slack offre une meilleure expérience utilisateur, une découverte automatique des canaux et une sécurité améliorée via OAuth.

Besoin d'aide avec des configurations avancées ou vous avez des problèmes ? Consultez notre guide de dépannage ou contactez le support.

Aperçu

Commencer

Rapports

Intégrations

Configuration de l'Intégration Slack

Aperçu

Types d'Alertes Pris en Charge

Prérequis

Étape 1 : Installer l'Application PyQueryHub Slack

1.1 Naviguer vers l'Application PyQueryHub Slack

1.2 Autoriser l'Application

1.3 Configurer le Canal par Défaut

1.4 Inviter le Bot (Optionnel)

Étape 2 : Connecter Votre Espace de Travail Slack à PyQueryHub

2.1 Accéder aux Paramètres d'Intégration Slack

2.2 S'Authentifier avec Slack

2.3 Configurer les Canaux de Notification

2.4 Enregistrer la Configuration

Étape 3 : Configurer les Alertes pour Utiliser Slack

3.1 Créer ou Modifier une Alerte

3.2 Sélectionner les Canaux de Notification

3.3 Enregistrer l'Alerte

Format des Messages Slack

Message d'Alerte Déclenchée

Message d'Alerte Résolue

Message d'Alerte de Notebook

Configuration Avancée

Plusieurs Canaux Slack

Organisation des Canaux

Dépannage

Problèmes Courants

Tester Votre Configuration

Obtenir de l'Aide

Considérations de Sécurité

Sécurité de l'Application OAuth

Sécurité de l'Intégration

Confidentialité des Données

Exemples

Alerte de Ventes E-commerce

Surveillance de la Santé du Système

Suivi de Campagne Marketing

Meilleures Pratiques

1. Nommage des Canaux

2. Fréquence des Alertes

3. Clarté des Messages

4. Coordination d'Équipe

Alternative : Intégration de Webhook Personnalisée

Configuration Étape par Étape du Webhook

1. Créer une Application Slack

2. Activer les Webhooks Entrants

3. Copier l'URL du Webhook

4. Configurer dans PyQueryHub

Configuration Avancée du Webhook

Spécifications Techniques

Formatage des Messages

Gestion des Erreurs et Codes de Réponse

Limitation de Taux

Fonctionnalités de Sécurité

Quand Utiliser des Webhooks Personnalisés