Configuración de la Integración con Slack

Aprenda cómo configurar las notificaciones de Slack para sus alertas de PyQueryHub usando la aplicación oficial PyQueryHub Slack y los canales de notificación.

Resumen

PyQueryHub se integra con Slack a través de la Aplicación PyQueryHub Slack que instala directamente en su espacio de trabajo de Slack. Una vez configurada, sus alertas enviarán automáticamente notificaciones a sus canales de Slack cuando se cumplan las condiciones.

Tipos de Alertas Soportadas

Alertas de Datos: Notificar cuando los resultados de consulta cumplan condiciones específicas
Alertas de Notebooks: Enviar notificaciones desde notebooks de Python
Resolución de Alertas: Notificar cuando las condiciones de alerta vuelvan a la normalidad

Requisitos Previos

Antes de configurar los hooks de Slack, asegúrese de tener:

✅ Suscripción Activa: Los canales de notificación requieren una suscripción de pago
✅ Acceso de Administrador de Slack: Permiso para crear webhooks entrantes en su espacio de trabajo
✅ Alerta de PyQueryHub: Una alerta configurada que desee enviar a Slack

Paso 1: Instalar la Aplicación PyQueryHub Slack

1.1 Navegar a la Aplicación PyQueryHub Slack

Vaya a la Página del Directorio de Aplicaciones PyQueryHub Slack
Haga clic en "Añadir a Slack"
Inicie sesión en su espacio de trabajo de Slack si se le solicita

1.2 Autorizar la Aplicación

Seleccionar Espacio de Trabajo: Elija el espacio de trabajo de Slack donde desea instalar PyQueryHub
Revisar Permisos: La aplicación solicitará permisos para:
- Enviar mensajes a canales
- Leer información del canal
- Acceder a información de usuario para menciones
Haga clic en "Permitir" para otorgar permisos

1.3 Configurar Canal Predeterminado

Seleccionar Canal Predeterminado: Elija dónde se publicarán las notificaciones de PyQueryHub por defecto
Opciones de Canal:
- Canales públicos: Cualquier canal público en su espacio de trabajo
- Canales privados: Canales privados de los que es miembro
- Mensajes directos: Enviar alertas vía DM
Haga clic en "Instalar Aplicación" para completar la instalación

1.4 Invitar al Bot (Opcional)

Para canales privados o funcionalidad mejorada:

Vaya al canal de Slack donde desea recibir notificaciones
Escriba /invite @PyQueryHub para añadir el bot al canal
El bot confirmará que ha sido añadido y está listo para enviar alertas

Paso 2: Conectar Su Espacio de Trabajo de Slack a PyQueryHub

2.1 Acceder a la Configuración de Integración de Slack

Navegue a Configuración → Integraciones → Slack
Haga clic en "Conectar Espacio de Trabajo de Slack"

2.2 Autenticarse con Slack

Autorización OAuth: Será redirigido a Slack para la autenticación
Seleccionar Espacio de Trabajo: Elija el espacio de trabajo donde instaló la aplicación PyQueryHub
Confirmar Conexión: Haga clic en "Permitir" para conectar su espacio de trabajo
Verificación: Será redirigido de vuelta a PyQueryHub con confirmación

2.3 Configurar Canales de Notificación

Después de conectar su espacio de trabajo:

Navegue a Configuración → Canales de Notificación
Haga clic en "Añadir Canal"
Complete la configuración del canal:

Campo	Valor	Ejemplo
Alias	Nombre descriptivo para este canal	`"Alertas DevOps"`
Tipo	Seleccione `Slack` del menú desplegable	`Slack`
Destino	Seleccione de sus canales de Slack	`#alertas-general`
Espacio de Trabajo	Su espacio de trabajo de Slack conectado	`MiEmpresa Slack`

2.4 Guardar Configuración

Haga clic en "Crear Canal" para guardar su canal de notificación de Slack.

Paso 3: Configurar Alertas para Usar Slack

3.1 Crear o Editar Alerta

Navegue a su Informe → Alertas
Cree una nueva alerta o edite una existente

3.2 Seleccionar Canales de Notificación

En la sección Canales:

Seleccione su canal de Slack del menú desplegable
Añada múltiples canales si es necesario (email, Slack, etc.)
Configure las reglas de alerta según sea necesario

3.3 Guardar Alerta

Haga clic en "Guardar Alerta" para activar las notificaciones de Slack.

Formato de Mensajes de Slack

Mensaje de Alerta Activada

🚨 Alerta Activada: Alerta Diaria de Ventas

📊 Informe: Panel de Ventas T4  
⚠️  Alerta: Alerta Diaria de Ventas  
📅 Cuando: 15 dic 2024 2:14 PM

🔎 Reglas Incumplidas:
1. Ingresos < 10000 (Actual: 8750)
2. Nuevos Clientes < 50 (Actual: 23)

[Ver Informe]

Mensaje de Alerta Resuelta

✅ Alerta Resuelta: Alerta Diaria de Ventas

📊 Informe: Panel de Ventas T4
✅ Esta alerta ha vuelto a un estado 'normal'.

Resuelta: 15 dic 2024 4:32 PM

[Ver Informe]

Mensaje de Alerta de Notebook

📔 Alerta de Notebook: Actualización de Procesamiento de Datos

Estado: Éxito ✅  
Mensaje: ETL diario completado exitosamente. 1,247 registros procesados.

[Ver Informe]

Configuración Avanzada

Múltiples Canales de Slack

Puede crear múltiples canales de Slack para diferentes propósitos:

Nombre del Canal	Propósito	Destino del Webhook
`Alertas Críticas`	Problemas de alta prioridad	`#alertas-criticas`
`Informes Diarios`	Notificaciones rutinarias	`#informes-diarios`
`Alertas DevOps`	Problemas de infraestructura	`#alertas-devops`

Organización de Canales

Mejores Prácticas:

Use alias descriptivos ("Alertas Equipo de Ventas" vs "Canal Slack 1")
Cree canales separados para diferentes prioridades de alerta
Considere usar diferentes canales de Slack para diferentes equipos

Solución de Problemas

Problemas Comunes

❌ "Espacio de trabajo de Slack no conectado"

Causa: Aplicación PyQueryHub no instalada o conexión OAuth expirada
Solución: Reinstale la aplicación PyQueryHub Slack y reconecte su espacio de trabajo

❌ "Acceso al Canal Restringido"

Causa: Sin suscripción activa o bot no invitado a canales privados
Solución: Actualice a un plan de pago y asegúrese de que el bot esté invitado a los canales objetivo

❌ Los mensajes no aparecen en Slack

Causa: El bot puede no tener permisos, el canal no existe, o el webhook fue revocado
Solución: Verifique los permisos del bot, asegúrese de que el canal objetivo sea accesible, verifique la validez del webhook

❌ Error HTTP 400 "invalid_payload"

Causa: JSON mal formado en la solicitud del webhook o campos requeridos faltantes
Solución: Verifique el formato del mensaje, asegúrese de que el campo text o blocks esté presente

❌ Error HTTP 403 "channel_is_archived"

Causa: El canal objetivo ha sido archivado en Slack
Solución: Desarchivar el canal o actualizar el canal de notificación a un canal activo

❌ Error HTTP 404 "channel_not_found"

Causa: El canal fue eliminado o el webhook no tiene permisos de acceso
Solución: Verifique que el canal existe y recree el webhook si es necesario

❌ HTTP 429 Límite de Tasa Excedido

Causa: Enviando mensajes más rápido que 1 por segundo
Solución: PyQueryHub maneja esto automáticamente con lógica de reintentos, no se necesita acción

❌ "La alerta no se activa"

Causa: Las reglas de alerta pueden no cumplirse o la integración de Slack está desconectada
Solución: Verifique las condiciones de alerta y el estado de conexión del espacio de trabajo de Slack

❌ "URL del webhook revocada por Slack"

Causa: La URL fue expuesta accidentalmente o detectada como comprometida
Solución: Cree una nueva URL de webhook y actualice el canal de notificación de PyQueryHub

Probar Su Configuración

Crear Alerta de Prueba: Configure una alerta simple que definitivamente se activará
Usar Umbral Bajo: Establezca condiciones de alerta que pueda cumplir fácilmente para probar
Verificar Canal de Slack: Verifique que los mensajes aparezcan con el formato correcto
Probar Comandos del Bot: Intente mencionar @PyQueryHub en canales para probar la capacidad de respuesta
Probar Resolución: Asegúrese de que los mensajes de resolución funcionen cuando las condiciones mejoren

Obtener Ayuda

Si encuentra problemas:

Verifique que la aplicación PyQueryHub esté correctamente instalada en su espacio de trabajo de Slack
Verifique los permisos del espacio de trabajo de Slack y el acceso del bot al canal
Asegúrese de que su suscripción de PyQueryHub incluya canales de notificación
Pruebe las URL de webhook manualmente para verificar que funcionen correctamente
Revise los registros de auditoría del espacio de trabajo de Slack para cualquier cambio de permisos de aplicación
Contacte a soporte con mensajes de error específicos y detalles del espacio de trabajo

Consideraciones de Seguridad

Seguridad de la Aplicación OAuth

🔐 Permisos de la Aplicación: La aplicación PyQueryHub Slack solo solicita permisos necesarios para mensajería
🔄 Gestión de Tokens: Los tokens OAuth se gestionan de forma segura y se pueden revocar desde la configuración del espacio de trabajo de Slack
👥 Control del Espacio de Trabajo: Los administradores del espacio de trabajo de Slack pueden gestionar las instalaciones y permisos de aplicaciones
📝 Registro de Auditoría: Todas las instalaciones y permisos de aplicaciones se registran en los registros de auditoría del espacio de trabajo de Slack

Seguridad de la Integración

🔐 Transmisión Cifrada: Todos los mensajes enviados a Slack usan cifrado HTTPS
🛡️ Validación de Token: Slack valida todas las solicitudes de webhook entrantes para autenticidad
🚫 Revocación de URL: Slack revoca automáticamente las URL de webhook si se detectan como comprometidas
📊 Límite de Tasa: Slack impone límites de tasa para prevenir spam y abuso

Privacidad de Datos

🔒 Datos Sensibles: Sea consciente de qué datos aparecen en los mensajes de alerta
🏢 Canales Internos: Use canales privados de Slack para alertas confidenciales
📋 Cumplimiento: Asegúrese de que la integración de Slack cumpla con los requisitos de cumplimiento de su organización

Ejemplos

Alerta de Ventas de Comercio Electrónico

Escenario: Alerta cuando los ingresos diarios caen por debajo del objetivo

Configuración de Alerta:
  Nombre: "Alerta de Ingresos Diarios"
  Canal: "Slack Equipo de Ventas"
  Reglas: 
    - Ingresos < 50000
  Frecuencia: Diario a las 6 PM

Mensaje de Slack:

🚨 Alerta Activada: Alerta de Ingresos Diarios

📊 Informe: Panel de Ventas Diarias
⚠️  Alerta: Alerta de Ingresos Diarios  
📅 Cuando: 15 dic 2024 6:00 PM

🔎 Reglas Incumplidas:
1. Ingresos < 50000 (Actual: 42,750)

[Ver Informe]

Monitoreo de Salud del Sistema

Escenario: Monitorear métricas de rendimiento de la base de datos

Configuración de Alerta:
  Nombre: "Alerta de Rendimiento BD"  
  Canal: "Slack DevOps"
  Reglas:
    - Tiempo de Respuesta de Consulta > 2000ms
    - Conexiones Activas > 100

Seguimiento de Campañas de Marketing

Escenario: Rastrear tasas de conversión para campañas

Configuración de Alerta:
  Nombre: "Alerta de Baja Conversión"
  Canal: "Slack Equipo de Marketing"  
  Reglas:
    - Tasa de Conversión < 2.5%
    - Costo por Adquisición >

Mejores Prácticas

1. Nomenclatura de Canales

✅ Use nombres descriptivos y consistentes
✅ Incluya el equipo/propósito en el nombre
✅ Ejemplo: "Equipo de Ventas - Alertas de Ingresos"

2. Frecuencia de Alertas

⏰ Evite el spam: No configure alertas con demasiada frecuencia
📅 Horas laborales: Considere cuándo su equipo revisa Slack
🔕 Horas de silencio: Respete los horarios del equipo para alertas no críticas

3. Claridad del Mensaje

📊 Contexto: Incluya nombres de informes y enlaces
🔢 Valores específicos: Muestre valores reales vs esperados
⚡ Accionable: Deje claro qué necesita atención

4. Coordinación del Equipo

👥 Asignar propiedad: Deje claro quién debe responder a las alertas
📋 Documentar procedimientos: Cree guías de ejecución para escenarios comunes de alerta
🔄 Revisar regularmente: Audite y actualice las configuraciones de alerta

Alternativa: Integración de Webhook Personalizada

Si su organización requiere un enfoque de webhook personalizado en lugar de la aplicación PyQueryHub Slack:

Configuración Paso a Paso del Webhook

1. Crear una Aplicación de Slack

Vaya a Slack API y haga clic en "Crear Nueva Aplicación"
Elija "Desde cero"
Ingrese Nombre de la Aplicación: "Notificaciones PyQueryHub"
Seleccione su espacio de trabajo de Slack
Haga clic en "Crear Aplicación"

2. Habilitar Webhooks Entrantes

En la configuración de su aplicación, navegue a "Webhooks Entrantes"
Cambie "Activar Webhooks Entrantes" a Activado
Haga clic en "Añadir Nuevo Webhook al Espacio de Trabajo"
Seleccione el canal objetivo donde se publicarán las notificaciones
Haga clic en "Permitir" para autorizar el webhook

3. Copiar URL del Webhook

Después de la autorización, recibirá una URL de webhook como:

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

Importante: Mantenga esta URL segura y nunca la comparta públicamente.

4. Configurar en PyQueryHub

Navegue a Configuración → Canales de Notificación
Haga clic en "Añadir Canal"
Ingrese los detalles del canal:
- Alias: "Alertas Slack Personalizadas"
- Tipo: "Slack"
- Destino: Pegue su URL de webhook
Haga clic en "Crear Canal"

Configuración Avanzada del Webhook

Especificaciones Técnicas

Formato de Solicitud HTTP:

Método: POST
Content-Type: application/json
Formato de URL: https://hooks.slack.com/services/T{ID_ESPACIO_TRABAJO}/B{ID_BOT}/X{TOKEN_VERIFICACION}

Carga Útil Básica del Mensaje:

{
    "text": "🚨 Alerta Activada: Alerta Diaria de Ventas",
    "blocks": [
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "*Informe:* Panel de Ventas T4\n*Alerta:* Alerta de Ingresos Diarios"
            }
        }
    ]
}

Formato de Mensajes

PyQueryHub formatea automáticamente los mensajes con:

Formato de texto enriquecido usando la sintaxis markdown de Slack (mrkdwn)
Diseños Block Kit con secciones, divisores y campos
Elementos interactivos como botones para enlaces de informes
Indicadores de estado con emojis y codificación de color
Máximo 100 archivos adjuntos por mensaje (límite de Slack)

Manejo de Errores y Códigos de Respuesta

Nuestra integración de webhook maneja todos los códigos de respuesta HTTP de Slack:

Respuestas de Éxito:

200 OK: Mensaje publicado exitosamente

Respuestas de Error del Cliente:

400 Bad Request:
- invalid_payload: JSON mal formado o campos requeridos faltantes
- no_text: El mensaje carece tanto de contenido text como blocks
- too_many_attachments: Se excedió el límite de 100 archivos adjuntos
403 Forbidden:
- channel_is_archived: El canal objetivo ha sido archivado
- action_prohibited: Permisos insuficientes
404 Not Found:
- channel_not_found: El canal no existe o el bot no tiene acceso
410 Gone:
- channel_is_archived: Canal archivado permanentemente

Respuestas de Error del Servidor:

500 Internal Server Error: Problemas del servicio Slack
503 Service Unavailable: Inactividad temporal de Slack

Límite de Tasa

Límite de Tasa Estándar: 1 mensaje por segundo por webhook
Capacidad de Ráfaga: Se permiten ráfagas cortas, luego se limita
Respuesta 429: Devuelto cuando se excede el límite de tasa
Lógica de Reintento: PyQueryHub reintenta automáticamente con retroceso exponencial

Características de Seguridad

Seguridad de URL:

Las URLs de webhook son secretos únicos - trátelas como contraseñas
Formato: https://hooks.slack.com/services/T{ESPACIO_TRABAJO}/B{BOT}/X{TOKEN}
Revocación Automática: Slack escanea activamente URLs expuestas y las revoca
Sin Recuperación: Una vez revocadas, las URLs de webhook no se pueden restaurar (debe crear nuevas)

Medidas de Seguridad de PyQueryHub:

Almacenamiento Cifrado: Las URLs de webhook se cifran en nuestra base de datos usando AES-256
Detección Automática: Si Slack revoca un webhook, notificamos inmediatamente a los administradores
Control de Acceso: Solo los administradores del espacio de trabajo pueden configurar canales de webhook
Registro de Auditoría: Todos los cambios de configuración de webhook se registran con marcas de tiempo y detalles del usuario
Prueba de Conexión: La validez del webhook se prueba antes de guardar la configuración

Limitaciones del Webhook (por diseño):

No puede anular el canal, nombre de usuario o ícono configurados
No puede eliminar mensajes una vez publicados en Slack
Sin historial de mensajes - los webhooks son comunicación unidireccional
Sin respuestas interactivas - no puede recibir entrada del usuario desde Slack

Cuándo Usar Webhooks Personalizados

Seguridad Empresarial: Su organización restringe las instalaciones de aplicaciones de terceros
Control Personalizado: Necesita control total sobre el formato y entrega de mensajes
Sistemas Heredados: Integración con infraestructura de webhook existente
Requisitos de Cumplimiento: Su organización requiere integraciones basadas en webhooks

Nota: Aunque los webhooks personalizados proporcionan más control, la aplicación PyQueryHub Slack ofrece mejor experiencia de usuario, descubrimiento automático de canales y seguridad mejorada a través de OAuth.

¿Necesita ayuda con configuraciones avanzadas o tiene problemas? Consulte nuestra guía de solución de problemas o contacte a soporte.

Resumen

Comenzar

Informes

Integraciones

Configuración de la Integración con Slack

Resumen

Tipos de Alertas Soportadas

Requisitos Previos

Paso 1: Instalar la Aplicación PyQueryHub Slack

1.1 Navegar a la Aplicación PyQueryHub Slack

1.2 Autorizar la Aplicación

1.3 Configurar Canal Predeterminado

1.4 Invitar al Bot (Opcional)

Paso 2: Conectar Su Espacio de Trabajo de Slack a PyQueryHub

2.1 Acceder a la Configuración de Integración de Slack

2.2 Autenticarse con Slack

2.3 Configurar Canales de Notificación

2.4 Guardar Configuración

Paso 3: Configurar Alertas para Usar Slack

3.1 Crear o Editar Alerta

3.2 Seleccionar Canales de Notificación

3.3 Guardar Alerta

Formato de Mensajes de Slack

Mensaje de Alerta Activada

Mensaje de Alerta Resuelta

Mensaje de Alerta de Notebook

Configuración Avanzada

Múltiples Canales de Slack

Organización de Canales

Solución de Problemas

Problemas Comunes

Probar Su Configuración

Obtener Ayuda

Consideraciones de Seguridad

Seguridad de la Aplicación OAuth

Seguridad de la Integración

Privacidad de Datos

Ejemplos

Alerta de Ventas de Comercio Electrónico

Monitoreo de Salud del Sistema

Seguimiento de Campañas de Marketing

Mejores Prácticas

1. Nomenclatura de Canales

2. Frecuencia de Alertas

3. Claridad del Mensaje

4. Coordinación del Equipo

Alternativa: Integración de Webhook Personalizada

Configuración Paso a Paso del Webhook

1. Crear una Aplicación de Slack

2. Habilitar Webhooks Entrantes

3. Copiar URL del Webhook

4. Configurar en PyQueryHub

Configuración Avanzada del Webhook

Especificaciones Técnicas

Formato de Mensajes

Manejo de Errores y Códigos de Respuesta

Límite de Tasa

Características de Seguridad

Cuándo Usar Webhooks Personalizados