Conectar un canal de Slack por la API¶

Esta página es para administradores que quieren recibir en un canal de Slack notificaciones sobre su organización. Muestra cómo conectar un canal, qué dice un mensaje, cómo probar y qué hacer cuando Slack ya no recibe nada. Cómo hacer una petición a OS (dirección, inicio de sesión, páginas, errores) está en La API de acceso.

Antes de empezar¶

• Slack debe estar activado en este entorno. Si está desactivado, OS responde 409 al conectar, cambiar y probar.
• Necesitas write sobre notification_channel (Tipos y acciones). El rol de administrador lo tiene, y está en el servicio de cada organización, sean cuales sean sus planes.
• En Slack, crea un incoming webhook para el canal (en Slack: una app con Incoming Webhooks, luego Add New Webhook to Workspace y elige el canal). Slack te da una dirección que empieza por https://hooks.slack.com/services/.

Quien tiene la dirección puede escribir en ese canal. OS la guarda cifrada y no la vuelve a mostrar nunca, ni siquiera a ti. No la guardes en ningún otro sitio.

Conectar¶

curl -s -X POST "$OS/api/v1/organisations/$ORG/slack-webhooks" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.slack.com/services/T.../B.../...", "label": "#ops",
       "kinds": ["service.plan_lapsed"], "locale": "en"}'

{"id": "swh_...", "label": "#ops", "kinds": ["service.plan_lapsed"], "locale": "en",
 "state": "active", "consecutive_failures": 0, "last_delivered_at": null,
 "allowed_actions": ["see", "write", "delete"]}

• kinds nombra las clases de notificación que van al canal. Solo las clases que tratan de la propia organización pueden ir a un canal: un plan que terminó (service.plan_lapsed), un webhook que falla o se desactivó (events.webhook_failing, events.webhook_disabled) y un canal de Slack que ya no recibe nada (notifications.slack_failing). Nada sobre personas va nunca a Slack.
• locale es nl, en, de, fr o es; sin él, neerlandés.
• Una organización conecta como máximo cinco canales por defecto.

Qué dice un mensaje¶

Todos los del canal de Slack leen los mensajes, también personas que no son miembros de tu organización en OS. Por eso un mensaje contiene solo: la clase de notificación como la nombra el centro de notificaciones (por ejemplo «Un plan terminó»), en el idioma de la conexión, el nombre de la organización, como mucho una fecha o una cantidad (en un plan que terminó: la fecha en que acabó) y un enlace a OS. Nunca el nombre o la dirección de una persona, un importe, el nombre de un plan, el nombre de un webhook ni nada que alguien haya escrito.

A qué canales llega una notificación: solo a los de tu propia organización, y solo las notificaciones sobre tu propia organización. El canal de un socio nunca recibe una notificación sobre uno de sus clientes; los administradores del socio las leen en OS y por correo. Un cliente sin canal propio no recibe nada en Slack.

Mientras las reglas de tu organización tengan un forbid sobre notification_channel, OS no publica nada en ninguno de sus canales de Slack, tampoco lo que ya esperaba para publicarse.

Probar, cambiar, desconectar¶

Una prueba llega al canal en segundos. Si llegó, lo muestra last_delivered_at. Mientras las reglas de tu organización prohíban notification_channel, una prueba sigue respondiendo 202 y no llega nada.

Cuando Slack ya no recibe nada¶

• revoked: Slack dijo que el webhook ya no existe, o que el canal se archivó. Crea un webhook nuevo en Slack y ponlo en la conexión con PATCH; vuelve a estar active al instante.
• failing: las publicaciones fallaron una y otra vez (cinco seguidas por defecto). OS no publica nada más hasta que pongas una dirección nueva o envíes una prueba que llegue.

En ambos casos, los administradores de tu organización reciben una notificación en OS y por correo, como mucho una vez por semana y por conexión. Cada cambio queda en el registro de auditoría, sin la dirección.

A dónde van los mensajes¶

Slack es un servicio de Slack Technologies en Estados Unidos. OS envía solo el contenido descrito arriba, y solo a los canales que conectas. Una organización que no puede enviar nada a Estados Unidos prohíbe notification_channel en sus reglas.