Slack

O Slack conecta o workspace de cada cliente ao seu produto nos dois sentidos. O usuário autoriza uma vez pelo botão do Slack, e a partir daí as mensagens que interessam — DMs, menções e os canais que ele escolheu observar — chegam ao seu backend por webhook, e o seu produto pode responder no mesmo lugar.

Na prática: um assistente que já atende pelo WhatsApp passa a atender pelo Slack sem nova arquitetura. O usuário manda "qual o status da proposta 4471?" numa DM, o evento chega ao seu endpoint em segundos, e a resposta volta pelo POST /messages/send como se tivesse sido digitada pelo próprio usuário.

Está em alpha. São 8 endpoints, e a lista do que falta é longa e honesta: não há como desconectar um workspace pela API, não há listar nem apagar dispatcher, o token não é renovado, e o app Slack ainda depende de aprovação da Slack para ser instalado fora do workspace de desenvolvimento. Ler a §15 antes de prometer qualquer coisa a cliente não é recomendação, é requisito.

Atenção ao prefixo. O app Hono usa basePath('/slack') e os routers são montados em /api/v1/slack/.... A rota completa fica /slack/api/v1/slack/messages/send, com o nome do módulo repetido. É o que o código faz hoje. Toda rota da §9 está na forma completa e real.

---

O cenário. Seu produto precisa falar com o usuário dentro do Slack da empresa dele. Não o seu Slack — o dele. E não um workspace, mas o de cada cliente que você atende, cada um com seu próprio consentimento, seus próprios canais e sua própria política de segurança.

O que trava hoje.

• Um app Slack de verdade é um projeto, não um endpoint. Para instalar em mais de um workspace, o app precisa de distribuição pública ativada, o que a Slack condiciona a uma lista de requisitos: "Your app must support SSL for all of the following URLs", fluxo de onboarding para múltiplos workspaces, e pedir só as permissões necessárias, "admins screen these during approval" (Slack — Distributing Slack apps, consulta em 2026-08-16). Depois disso vem OAuth por workspace e um token por instalação para guardar e cifrar.
• A janela de resposta é de três segundos. A Slack é explícita: você deve "respond to the event request with an HTTP 2xx within three seconds", e falhando isso ela reenvia três vezes — "nearly immediately", depois de 1 minuto e depois de 5 minutos (Slack — Events API, consulta em 2026-08-16). Qualquer processamento síncrono dentro do handler vira mensagem duplicada em produção.
• Verificação de assinatura é obrigatória e fácil de errar. A Slack assina cada requisição, e a verificação exige o corpo bruto — reserializar o JSON antes de calcular o HMAC quebra a comparação de forma silenciosa. Some a isso a janela de tolerância de tempo contra reenvio de requisição capturada.
• O volume de um workspace inunda qualquer backend. Ligar o Events API sem filtro significa receber toda mensagem de todo canal, incluindo entrada e saída de gente, edição, remoção e mensagem de outros bots. Filtrar isso é código, e é código que precisa rodar antes da fila, não depois.
• Ferramenta de automação não resolve multi-tenant. Zapier e Make são ótimos para um fluxo. Para cem clientes com cem workspaces, cada um com seus canais, o modelo de cobrança por tarefa e a ausência de contexto de tenant transformam a solução no problema.

O custo de não resolver. A soma é: um app distribuído aprovado, OAuth por workspace, cifra e ciclo de vida de token por instalação, verificação de assinatura com corpo bruto, ack em menos de três segundos com processamento assíncrono, e filtro de ruído. Nada disso é a sua regra de negócio, e tudo isso precisa existir antes do primeiro cliente ver valor.

---

OAuth por workspace, pronto. POST /connections/connect devolve a URL de autorização com o state cifrado; o callback troca o código por token, identifica o time e grava a conexão. O integrador não escreve OAuth.

Ack primeiro, trabalho depois. O handler de eventos verifica a assinatura, responde 200 e dispara a ingestão sem esperar. É a arquitetura que a janela de três segundos da Slack exige, e ela já está feita.

Filtro de ruído no lugar certo. A função shouldForward descarta subtipos de ruído (bot_message, message_changed, message_deleted, channel_join, channel_leave), deixa passar toda DM e todo grupo de DM, deixa passar qualquer mensagem que mencione o usuário conectado, e para canais comuns só entrega os que estão em watchedChannels. O que sai daqui é sinal.

Entrega pela infraestrutura que já existe. O dispatcher cria uma assinatura no Webhooks Engine — a mesma que o WPP e o WPP Business usam — com timeout de 10 segundos e três tentativas em backoff exponencial. Assinatura, retry e log de entrega não são reimplementados aqui.

---

Caso 1 — Um assistente ganha o Slack como canal sem nova arquitetura Cenário ilustrativo

Contexto. Produto de assistente para times de operações que já atendia por WhatsApp usando o building block WPP. Os clientes corporativos pediram Slack.

A dor. A primeira estimativa do time para "colocar Slack" foi de seis a oito semanas: app distribuído, OAuth por workspace, verificação de assinatura, ack em três segundos, filtro e uma fila de entrega própria. Nenhuma dessas semanas produziria uma linha de valor para o usuário — o assistente em si já existia.

A solução com o BB. O cliente conecta o workspace por POST /slack/api/v1/slack/connections/connect. Um POST /slack/api/v1/slack/dispatchers aponta para o mesmo endpoint que já recebia os eventos do WPP, com watchedChannels definindo os canais observados. O evento chega como slack.v1.message.received com o mesmo envelope de dispatcher que o time já sabia consumir. A resposta sai por POST /slack/api/v1/slack/messages/send.

O resultado. O canal novo reaproveita o consumidor existente. O trabalho que sobra é de produto — o que o assistente responde no Slack —, não de plataforma.

Caso 2 — Um alerta operacional chega no canal do cliente, não numa caixa de e-mail Cenário ilustrativo

Contexto. Plataforma de logística que avisa quando uma entrega ultrapassa a janela combinada.

A dor. Os avisos iam por e-mail para uma lista. Ninguém lia, porque a decisão sobre a entrega atrasada é tomada no canal #operacao-sp do Slack, onde o time já está. O e-mail chegava, era encaminhado para o Slack por uma pessoa, e o tempo de resposta era o tempo dessa pessoa.

A solução com o BB. O cliente conecta o workspace e a plataforma passa a postar em #operacao-sp por POST /messages/send. Como a mensagem é enviada com o token do usuário que instalou o app (as_user: true), ela aparece com identidade humana no canal, não como bot anônimo — o que muda a taxa de leitura.

O resultado. O aviso nasce onde a decisão acontece. E, como o mesmo dispatcher observa o canal, a resposta que o time escreve volta ao produto e vira registro de tratativa.

Caso 3 — O filtro de ruído é o que torna a ingestão viável Cenário ilustrativo

Contexto. Cliente com um workspace de 400 pessoas e cerca de 90 canais ativos.

A dor. Um piloto anterior, feito com uma ferramenta de automação genérica, ligou o Events API sem filtro. O backend recebeu tudo: entrada e saída de gente em canal, edição de mensagem, mensagem de outros bots, thread de canal irrelevante. O volume derrubou a fila no primeiro dia útil, e o custo por tarefa da ferramenta estourou o orçamento do piloto na primeira semana.

A solução com o BB. O shouldForward roda antes da entrega: descarta os cinco subtipos de ruído, entrega toda DM e MPIM, entrega qualquer texto contendo <@USER_ID> do usuário conectado, e para canais comuns exige que o canal esteja em watchedChannels. Os canais observados são ajustados por PATCH /dispatchers/:id sem recriar nada.

O resultado. Do workspace inteiro, chega ao backend a fração que tem endereço: conversa direta, menção explícita e os canais que alguém escolheu observar.

Caso 4 — Distribuir um app Slack tem um portão, e ele é público Referência de mercado

Contexto. Quem planeja "integrar Slack" costuma orçar a API e esquecer o processo de distribuição.

A dor do mercado. A própria Slack documenta que instalar em outros workspaces exige OAuth 2.0, SSL em todas as URLs e uma checklist de distribuição pública, e que "apps intended for commercial distribution should be submitted and approved for listing in the Slack Marketplace" (Slack — Distributing Slack apps, consulta em 2026-08-16). Distribuição não listada é possível para clientes iniciais, mas escopos de histórico de conversa passam por escrutínio, e o administrador de cada workspace corporativo ainda pode exigir aprovação individual.

Como a Catalisa endereça. O building block implementa o lado técnico inteiro — OAuth v2 com state cifrado, verificação de assinatura, ack de três segundos, escopos de usuário declarados e documentados. O runbook `docs/slack/SETUP.md` descreve o processo de criação do app, o manifesto pronto e a política de aprovação por tipo de workspace.

O resultado. O que resta ao cliente é a parte que ninguém pode fazer por ele: o processo de aprovação junto à Slack e ao administrador do workspace. Ressalva honesta: enquanto a revisão do app não sai, o alcance é o workspace de instalação. Está em §15.

---

Panorama. Colocar Slack dentro de um produto tem três caminhos. Construir o app direto na Slack Platform dá controle total e cobra em engenharia: distribuição, OAuth por workspace, ciclo de vida de token, assinatura, ack de três segundos. Usar uma ferramenta de automação — Zapier, Make, n8n — resolve um fluxo em uma tarde e cobra por execução, com o fluxo vivendo fora do seu código. Contratar uma plataforma de notificação — Knock, Courier — resolve muito bem o caminho de saída e quase não toca o de entrada.

O Slack da Catalisa fica num quarto lugar, estreito de propósito: é o transporte bidirecional por workspace, dentro de uma plataforma que o cliente já usa para identidade e entrega de eventos. Não compete em amplitude com o Zapier nem em orquestração com o Knock.

Preços consultados nas páginas públicas em 2026-08-16: Zapier, n8n, Knock, Courier, Make. Variam por região, plano e negociação.

Nossos diferenciais

1. O filtro roda antes da entrega, não depois. shouldForward é uma função pura, testada, que decide no processo do building block. Uma ferramenta de automação recebe tudo e filtra depois — e cobra por tudo que recebeu. Em workspace grande, essa diferença é a viabilidade do projeto.
2. O canal reaproveita a infraestrutura de entrega dos outros canais. O dispatcher do Slack é o mesmo padrão do WPP e do WPP Business, sobre o mesmo Webhooks Engine. Quem já consome WhatsApp consome Slack com o mesmo verificador de assinatura e a mesma semântica de retry.
3. A mensagem sai com identidade humana. O envio usa o token do usuário que instalou o app, com as_user: true. Em canal operacional, mensagem de bot anônimo é ignorada e mensagem com rosto é lida.
4. O token do workspace fica na plataforma do cliente, cifrado. AES-256-GCM sob chave mestra própria do módulo, no banco da própria Catalisa, sem terceiro no meio do caminho entre o Slack e o produto.

Quando escolher o concorrente. Se o problema é notificação de saída bem orquestrada — preferências por usuário, agrupamento, digest, múltiplos canais com fallback —, o Knock e o Courier resolvem hoje e este building block não resolve nunca, porque não é o que ele é. Se o time que precisa da integração é de negócio e não de engenharia, o Zapier entrega em uma tarde o que aqui exige um endpoint HTTP e um deploy. Se você precisa de Block Kit, modais, slash commands ou Socket Mode, a Slack Platform direta é o único caminho — nada disso está aqui (§15). E se você atende um workspace, o seu, construir direto é mais simples que adotar um building block em alpha. O Slack da Catalisa ganha num caso específico: ingestão bidirecional, muitos workspaces de muitos clientes, dentro de uma plataforma que já entrega WhatsApp pelo mesmo caminho.

---

Unidade de cobrança. Precificação em definição. O building block está em alpha e não tem preço fechado. Não há valor a informar, e não vamos inventar um.

O que dispara custo.

Comparação de custo — cenário: 20 clientes com 20 workspaces, cerca de 30 mil mensagens ingeridas e 10 mil enviadas por mês, depois do filtro de ruído.

Estimativas montadas sobre as tabelas públicas consultadas em 2026-08-16 e citadas na §5. São ordens de grandeza para orientar conversa, não proposta comercial. Os valores da Catalisa não estão definidos.

ROI. O retorno não está na linha de licença — para volume baixo, quase tudo é barato. Está em duas coisas. A primeira é o trabalho de plataforma que não é feito: app distribuído, OAuth por workspace, cifra de token, verificação de assinatura, ack de três segundos e filtro somam semanas que não produzem valor visível ao usuário. A segunda é o efeito do filtro no modelo de custo de qualquer ferramenta que cobre por evento: em workspace grande, a diferença entre contar tudo e contar o que tem endereço é de uma ordem de grandeza.

---

                    HTTP
                      │
  ┌───────────────────┴───────────────────────────────────────────────┐
  │ Hono app  basePath('/slack')                                       │
  │                                                                    │
  │  /api/v1/slack/connections   connectionRouter               (3)    │
  │  /api/v1/slack/dispatchers   dispatcherRouter               (2)    │
  │  /api/v1/slack/messages      messagesRouter                 (1)    │
  │  /api/v1/slack/channels      channelsRouter                 (1)    │
  │  /api/v1/slack/events        slackEventsRouter  ← Slack     (1)    │
  │  /health          /connected  (página de retorno pós-OAuth)        │
  └───────────────────┬───────────────────────────────────────────────┘
                      │
  ┌───────────────────┴───────────────────────────────────────────────┐
  │ services/                                                          │
  │   SlackConnectionService   OAuth v2, state cifrado, upsert          │
  │   SlackEventsService       assinatura, filtro de ruído, fan-out     │
  │   SlackSendService         chat.postMessage como o usuário          │
  │   SlackChannelsService     conversations.list                       │
  │   SlackDispatcherService   cria assinatura no Webhooks Engine       │
  └──────┬──────────────────────────────────────────┬─────────────────┘
         │                                          │
         ▼                                          ▼
  ┌──────────────────────┐              ┌────────────────────────────┐
  │ repositories/ Prisma │              │ @slack/web-api  WebClient  │
  │  schema "slack"      │              │  → api.slack.com           │
  │  2 modelos           │              └────────────────────────────┘
  └──────────────────────┘

Caminho de uma mensagem que entra

  Usuário escreve no Slack
          │
          ▼
  POST /slack/api/v1/slack/events        (rota pública — sem token da plataforma)
          │
          ├─ 1. lê o corpo BRUTO como texto, antes de qualquer parse
          ├─ 2. verifica x-slack-signature contra SLACK_SIGNING_SECRET
          │       HMAC-SHA256 de  v0:{timestamp}:{corpo}
          │       recusa se o timestamp desviar mais de 5 minutos  → 401
          ├─ 3. faz o parse do JSON                                → 400 se inválido
          ├─ 4. url_verification? devolve o challenge em texto puro
          │
          ├─ 5. event_callback de `message` ou `app_mention`:
          │        dispara ingestEvent SEM aguardar  ────────┐
          │                                                  │
          └─ 6. responde 200 imediatamente ◀─────────────────┼── janela de 3s da Slack
                                                             │
                                                             ▼
                                              SlackEventsService.ingestEvent
                                                             │
                                    ┌────────────────────────┴───────────────────┐
                                    │ 1. conexão por (team_id, authorizations[0]) │
                                    │ 2. dispatchers ACTIVE da conexão            │
                                    │ 3. união dos watchedChannels                │
                                    │ 4. shouldForward(...)                       │
                                    │      descarta bot_message, message_changed, │
                                    │      message_deleted, channel_join/leave     │
                                    │      passa: im, mpim, menção <@user>,        │
                                    │             canal em watchedChannels         │
                                    │ 5. emitSlackPublic(slack.v1.message.received)│
                                    └────────────────────────┬───────────────────┘
                                                             ▼
                                                    Webhooks Engine
                                              assinatura · retry · log
                                                             ▼
                                                   endpoint do cliente

Decisões não óbvias.

• A assinatura é verificada em toda requisição, inclusive no url_verification. Muita implementação libera o desafio de verificação antes de checar assinatura, porque é o primeiro POST que a Slack manda. Aqui não: sem SLACK_SIGNING_SECRET configurado, ou com assinatura inválida, a resposta é 401 mesmo para o desafio. Custa um passo a mais na configuração e fecha um caminho em que qualquer um posta na sua rota pública.
• O corpo é lido como texto antes de qualquer parse. await c.req.text() vem primeiro, e o HMAC é calculado sobre esses bytes. Fazer o parse e reserializar muda espaçamento e ordem de chave, e a assinatura deixa de bater — de forma silenciosa e intermitente, que é o pior modo de falhar.
• A comparação usa timingSafeEqual, com verificação de comprimento antes. Comparação de string com === vaza informação por tempo de execução. E o timingSafeEqual do Node lança exceção com buffers de tamanhos diferentes, por isso o comprimento é conferido antes.
• Tolerância de 5 minutos no timestamp. Requisição capturada e reenviada depois disso é rejeitada. Cinco minutos é a folga que absorve relógio dessincronizado sem abrir janela de repetição relevante.
• A ingestão é disparada e esquecida. O void service.ingestEvent(...) sai do caminho da resposta de propósito: a Slack exige 2xx em três segundos e reenvia três vezes se não receber (Slack — Events API, 2026-08-16). Processar antes de responder produz mensagem duplicada sob carga. O preço é que uma falha na ingestão vira log de warn, não erro HTTP — o cliente do Slack não fica sabendo.
• Erro de ingestão é sempre não fatal. Conexão não encontrada, dispatcher ausente ou falha de publicação não derrubam a resposta. Evento de workspace que ninguém conectou é ignorado em silêncio, o que é o comportamento certo para uma rota pública.
• O app OAuth é global, não por organização. SLACK_CLIENT_ID, SLACK_CLIENT_SECRET e SLACK_CALLBACK_URL vêm do ambiente e são registrados uma vez no container. É uma diferença deliberada em relação ao Calendar, que guarda credenciais OAuth por tenant: no Slack existe um app da plataforma, e cada cliente instala esse app no workspace dele. O trade-off é que a tela de consentimento leva a marca do app da plataforma, não a do cliente.
• O envio usa as_user: true. A mensagem sai com a identidade do usuário que instalou, não de um bot. É intencional — o token pedido é user_scope, não bot token — e tem consequência: o app precisa do escopo chat:write de usuário, e a mensagem conta como escrita por aquela pessoa.
• O filtro considera a união dos watchedChannels de todos os dispatchers ativos. Se um dispatcher observa #a e outro observa #b, a mensagem de #a passa pelo filtro e é publicada uma vez; a separação por dispatcher acontece no Webhooks Engine, pelos filtros da assinatura.

Monolito vs. standalone. Em monolito, o Slack é resolvido pelo container TypeDI e o SlackDispatcherService fala com o Webhooks Engine por chamada local. Em standalone — o modo de produção — sobe como serviço próprio (porta 3029 no compose local) e o dispatcher usa a facade remota: sem MODULE_WEBHOOKS_ENGINE_URL configurado, POST /dispatchers responde 503. Está anotado no próprio stack de deploy.

---

Glossário

Modelo de dados — schema slack no PostgreSQL.

Enumerações

Escopos de usuário solicitados

O token de usuário só alcança as DMs daquele usuário e os canais em que ele já está. Não há caminho para ler conversa privada de terceiros.

Decisão do filtro de ruído

  evento chega
       │
       ▼
  subtype ∈ { bot_message, message_changed, message_deleted,
              channel_join, channel_leave } ?
       │ sim ──────────────────────────────────▶ DESCARTA
       │ não
       ▼
  channelType ∈ { im, mpim } ?
       │ sim ──────────────────────────────────▶ ENTREGA
       │ não
       ▼
  texto contém <@slackUserId da conexão> ?
       │ sim ──────────────────────────────────▶ ENTREGA  (menção)
       │ não
       ▼
  channelId ∈ união dos watchedChannels dos dispatchers ACTIVE ?
       │ sim ──────────────────────────────────▶ ENTREGA
       │ não ──────────────────────────────────▶ DESCARTA

Ciclo de vida da conexão

   POST /connections/connect
          │  gera state cifrado (organizationId + userId + redirectUrl)
          ▼
   usuário autoriza em slack.com/oauth/v2/authorize
          │
          ▼
   GET /connections/callback   (rota pública)
          │  decifra o state → oauth.v2.access → cifra o token → upsert
          ▼
     ┌──────────┐
     │  ACTIVE  │   reconectar faz upsert na mesma linha e limpa deletedAt
     └──────────┘

   Não há endpoint de desconexão — ver §15.
   Não há renovação de token — ver §15.

---

Prefixo real: /slack/api/v1/slack. O nome do módulo aparece duas vezes porque o app usa basePath('/slack') e os routers são montados sob /api/v1/slack. Em standalone, a base é https://slack.stg.catalisa.app.

Salvo indicação de rota pública, toda rota exige authMiddleware, o requirePermission(...) da tabela e requireOrganization — token sem organizationId recebe 403 com Organization context required.

Conexões — /slack/api/v1/slack/connections

Dispatchers — /slack/api/v1/slack/dispatchers

Mensagens e canais

Eventos do Slack — rota pública

Saúde e retorno de OAuth

---

POST /slack/api/v1/slack/connections/connect

Request

{ "redirectUrl": "https://app.suaempresa.com.br/integracoes/slack/pronto" }

Resposta 200

{ "authorizationUrl": "https://slack.com/oauth/v2/authorize?client_id=...&user_scope=im%3Ahistory%2C...&state=..." }

Note o user_scope: o fluxo pede token de usuário, não de bot.

Erros

---

POST /slack/api/v1/slack/dispatchers

Cria a regra de encaminhamento e, junto com ela, a assinatura no Webhooks Engine.

Request

{
  "connectionId": "8f14e45f-ceea-467a-9e1a-2b3c4d5e6f70",
  "teamId": "T01ABCDEF",
  "slackUserId": "U01ABCDEF",
  "endpointUrl": "https://api.suaempresa.com.br/hooks/slack",
  "watchedChannels": ["C01OPERACAO", "C02SUPORTE"],
  "customHeaders": { "X-Origem": "slack" }
}

Resposta 201

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "secret": "c0ffee…",
    "subscriptionId": "aaaa-bbbb-cccc-dddd"
  }
}

O secret de 32 bytes é gerado aqui e enviado ao Webhooks Engine como o cabeçalho x-webhook-secret de toda entrega. Ele aparece uma vez, nesta resposta. Não há endpoint para recuperá-lo.

A assinatura criada filtra slack.v1.message.received e slack.v1.message.sent, com timeout de 10 s e até 3 tentativas em backoff exponencial (1 s, 2 s, 4 s). O segundo evento é declarado mas não é emitido hoje — ver §15.

Erros

---

POST /slack/api/v1/slack/messages/send

Request

{
  "teamId": "T01ABCDEF",
  "slackUserId": "U01ABCDEF",
  "channelId": "C01OPERACAO",
  "text": "Entrega 4471 fora da janela. Quer que eu abra a tratativa?"
}

A tripla (organizationId do token, teamId, slackUserId) resolve a conexão e o token — o organizationId nunca vem do corpo.

Resposta 200

{ "data": { "correlationId": "1756742400.123456" } }

O correlationId é o ts da mensagem no Slack. É o que identifica a mensagem e o que se usa como thread_ts para responder em thread.

Erros

---

POST /slack/api/v1/slack/events

Rota pública, chamada pela Slack. Configure-a como Request URL em Event Subscriptions.

Cabeçalhos exigidos

Respostas

Payload publicado quando o evento passa no filtro — tipo slack.v1.message.received:

{
  "originalPayload": {
    "teamId": "T01ABCDEF",
    "slackUserId": "U01ABCDEF",
    "channelId": "C01OPERACAO",
    "channelType": "channel",
    "ts": "1756742400.123456",
    "threadTs": null,
    "senderId": "U09XYZ",
    "senderName": null,
    "text": "qual o status da proposta 4471?",
    "subtype": null,
    "files": []
  }
}

---

Do zero à primeira mensagem trafegando. Os comandos não foram executados ao escrever esta documentação — conferem com o código e os schemas Zod, mas trate-os como referência.

Pré-requisito: o app Slack precisa existir e estar configurado. O passo a passo completo, com manifesto pronto, está em `docs/slack/SETUP.md`. Sem SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_SIGNING_SECRET, SLACK_CALLBACK_URL e SLACK_CREDENTIAL_MASTER_KEY, nada abaixo funciona.

1. Autenticar no IAM

TOKEN=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@catalisa.app","password":"password123",
       "organizationId":"b0000000-0000-0000-0000-000000000001"}' | jq -r .accessToken)

BASE=https://slack.stg.catalisa.app/slack/api/v1/slack

2. Confirmar que a rota de eventos está protegida

curl -s -o /dev/null -w "%{http_code}\n" -X POST "$BASE/events" \
  -H "Content-Type: application/json" -d '{"type":"url_verification","challenge":"x"}'

Deve responder 401. Se responder 200, o SLACK_SIGNING_SECRET não está fazendo o que deveria — pare e corrija antes de seguir.

3. Conectar o workspace

curl -s -X POST "$BASE/connections/connect" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"redirectUrl":"https://slack.stg.catalisa.app/slack/connected"}' \
  | jq -r .authorizationUrl

Abra a URL, autorize no workspace, e o callback grava a conexão e redireciona.

4. Verificar a conexão

curl -s "$BASE/connections" -H "Authorization: Bearer $TOKEN" | jq

{
  "data": [
    { "id": "8f14e45f-…", "teamId": "T01ABCDEF", "teamName": "Acme",
      "slackUserId": "U01ABCDEF", "status": "ACTIVE" }
  ]
}

Guarde id, teamId e slackUserId — os três aparecem nas chamadas seguintes.

5. Descobrir os canais

curl -s -G "$BASE/channels" -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "teamId=T01ABCDEF" \
  --data-urlencode "slackUserId=U01ABCDEF" | jq

{ "data": [ { "id": "C01OPERACAO", "name": "operacao-sp", "isPrivate": false } ] }

6. Criar o dispatcher

curl -s -X POST "$BASE/dispatchers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "connectionId": "8f14e45f-…",
    "teamId": "T01ABCDEF",
    "slackUserId": "U01ABCDEF",
    "endpointUrl": "https://api.suaempresa.com.br/hooks/slack",
    "watchedChannels": ["C01OPERACAO"]
  }' | jq

Anote o secret — ele não volta nunca mais.

7. Enviar uma mensagem

curl -s -X POST "$BASE/messages/send" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"teamId":"T01ABCDEF","slackUserId":"U01ABCDEF",
       "channelId":"C01OPERACAO","text":"Integração ativa."}' | jq

{ "data": { "correlationId": "1756742400.123456" } }

8. Fechar o ciclo

Escreva uma DM para o usuário conectado, ou mencione-o em #operacao-sp. Seu endpoint recebe slack.v1.message.received em segundos.

Credenciais de staging. Nunca cole segredo de produção em documentação ou script — ver AMBIENTES.md.

---

Verificar a assinatura da entrega no seu endpoint

O Webhooks Engine assina a entrega, e o dispatcher acrescenta o x-webhook-secret gerado na criação. Confira os dois, e confira o segredo em tempo constante.

import { timingSafeEqual } from 'node:crypto'

app.post('/hooks/slack', express.raw({ type: 'application/json' }), (req, res) => {
  const recebido = Buffer.from(req.header('x-webhook-secret') ?? '')
  const esperado = Buffer.from(process.env.SLACK_DISPATCHER_SECRET)

  if (recebido.length !== esperado.length || !timingSafeEqual(recebido, esperado)) {
    return res.sendStatus(401)
  }

  // Responda rápido. Enfileire o trabalho.
  res.sendStatus(200)

  const { originalPayload } = req.body
  fila.add({ canal: 'slack', ...originalPayload })
})

Armadilhas.

• Responda antes de processar. O timeout do dispatcher é de 10 segundos; passar disso conta como falha e gera nova tentativa.
• A entrega não é exatamente-uma-vez. Três tentativas em backoff significam que o mesmo ts pode chegar duas vezes. Use ts + channelId como chave de idempotência.
• A assinatura RSA do Webhooks Engine é a defesa principal; o x-webhook-secret é a segunda camada. Ver Webhooks Engine.

Ajustar os canais observados sem recriar nada

curl -s -X PATCH "$BASE/dispatchers/$DISPATCHER_ID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"watchedChannels":["C01OPERACAO","C02SUPORTE","C03LOGISTICA"]}'

{ "ok": true }

Armadilhas.

• O corpo substitui a lista inteira. Não há acrescentar nem remover — mande sempre o conjunto completo.
• Só watchedChannels é atualizável. Para mudar endpointUrl ou customHeaders, crie outro dispatcher; não há DELETE para o antigo (§15).
• Tirar um canal da lista não para DM nem menção. Esses dois passam sempre, por desenho do filtro.
• O usuário conectado precisa estar no canal. Canal fora da participação dele não gera evento, por mais que esteja na lista.

Responder dentro da thread da mensagem recebida

O POST /messages/send não aceita thread_ts hoje (§15). A alternativa que funciona:

# O ts recebido no evento identifica a mensagem original
curl -s -X POST "$BASE/messages/send" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"teamId\":\"$TEAM\",\"slackUserId\":\"$USER\",
       \"channelId\":\"$CANAL\",
       \"text\":\"Sobre a proposta 4471: em análise desde ontem.\"}"

Armadilhas.

• A resposta vai para o canal, não para a thread. Em canal movimentado, ela se perde do contexto. Se thread é requisito do seu produto, isso é bloqueante hoje.
• O correlationId que volta é o ts da sua mensagem, e é o que você guarda para correlacionar resposta com pedido.
• O limite de 40.000 caracteres é do schema; a Slack tem os limites de renderização dela. Mensagem muito longa é truncada ou rejeitada pelo lado deles.

Diagnosticar por que nada chega ao seu endpoint

Em ordem, do mais comum ao mais raro:

Atalho: teste sempre com DM primeiro. DM ignora watchedChannels e elimina metade das causas possíveis em uma tentativa.

---

O padrão de dispatcher da casa

Slack, WPP e WPP Business resolvem o mesmo problema: pegar evento de um canal de mensagem e entregar ao sistema do cliente com garantia. Os três usam o mesmo Webhooks Engine por baixo.

   WhatsApp (Baileys)      WhatsApp (Meta Cloud)        Slack
          │                        │                      │
          ▼                        ▼                      ▼
   ┌────────────┐          ┌──────────────┐       ┌──────────────┐
   │  BB wpp    │          │ BB wpp-      │       │  BB slack    │
   │  wpp.v1.*  │          │ business     │       │ slack.v1.*   │
   └─────┬──────┘          └──────┬───────┘       └──────┬───────┘
         │                        │                      │
         └────────────┬───────────┴──────────────────────┘
                      ▼
          ┌───────────────────────────────┐
          │      Webhooks Engine          │
          │  assinatura RSA · retry ·     │
          │  log de entrega · filtros     │
          └───────────────┬───────────────┘
                          ▼
                endpoint único do cliente

O argumento comercial: um consumidor, três canais. O cliente escreve o verificador de assinatura e o tratamento de idempotência uma vez.

Onde o Slack difere dos irmãos, e vale saber antes de integrar:

A referência completa do padrão está em `docs/wpp/dispatchers.md`. O Slack é a versão mínima dele.

A diferença em relação ao Calendar. Os dois fazem OAuth com state cifrado e token AES-256-GCM no banco, mas o app OAuth mora em lugares diferentes: o Calendar guarda client_id e client_secret por organização, então a tela de consentimento leva a marca do cliente; o Slack usa um app da plataforma, vindo do ambiente, que cada cliente instala no workspace dele. Vem do modelo da própria Slack, em que um app distribuído é instalado em muitos workspaces. A consequência prática: no Calendar cada cliente passa pela verificação do Google sozinho; no Slack a aprovação do app é uma só, da plataforma, e é gargalo compartilhado (§15).

---

Variáveis de ambiente

Cuidado na primeira subida. SLACK_CLIENT_ID, SLACK_CLIENT_SECRET e SLACK_CALLBACK_URL são opcionais no schema de configuração e, quando ausentes, viram string vazia no container — o serviço sobe e só falha na primeira tentativa de conexão. A SLACK_CREDENTIAL_MASTER_KEY é lida direto de process.env, fora do schema de configuração, e valida o formato apenas no momento do uso. Confirme as cinco variáveis logo após o deploy chamando POST /connections/connect: se ela devolve uma authorizationUrl com o client_id certo, está tudo no lugar.

Dependências de infraestrutura

Limites e quotas

Não há proteção de taxa própria no envio. Se o seu produto disparar rajada em um canal, o limite da Slack será atingido e o chat.postMessage falhará. Controle a cadência do seu lado (§15).

Catálogo de erros

Observabilidade.

• GET /slack/health responde vida e versão do build. Não testa banco, nem Slack, nem Webhooks Engine.
• A ingestão loga em debug quando um evento é filtrado (Slack event noise-filtered — not forwarding) e quando não há dispatcher ativo. É o primeiro lugar a olhar quando "não chega nada".
• Falha de ingestão vira warn com Slack event ingest error (non-fatal) — nunca erro HTTP, porque a resposta à Slack já saiu.
• O histórico de entrega vive no Webhooks Engine, não aqui. Este building block não expõe endpoint de log de entrega (§15).

---

Isolamento entre tenants. O organizationId vem do claim assinado do JWT, nunca do corpo. Cada router define requireOrganization e devolve 403 quando falta. Nos caminhos de envio e de listagem de canais, a organização compõe a chave de busca da conexão: getDecryptedToken(organizationId, teamId, slackUserId) bate na chave única (organizationId, teamId, slackUserId). Passar teamId de outro cliente não resolve conexão nenhuma — retorna 404.

Na ingestão o caminho é o inverso, e precisa ser: o evento vem da Slack sem token da plataforma, então a organização é derivada da conexão encontrada por (teamId, slackUserId), e é ela que vai no emitSlackPublic. A entrega herda o tenant do dono do workspace.

A rota pública se defende por assinatura. POST /events não tem autenticação da plataforma — a Slack não carrega o nosso token. A defesa é o HMAC-SHA256 sobre v0:{timestamp}:{corpo bruto} com o SLACK_SIGNING_SECRET, comparado em tempo constante, com tolerância de 5 minutos no timestamp contra reenvio de requisição capturada. A verificação vale para toda requisição, inclusive o desafio de verificação de URL: sem segredo configurado, a resposta é 401, e não um caminho aberto.

Como as credenciais OAuth são protegidas — evidência no código.

Nada de token volta pela API. GET /connections seleciona campo a campo — id, teamId, teamName, slackUserId, status — e a coluna accessToken não está na projeção. Não existe endpoint que devolva token. O secret do dispatcher aparece uma única vez, na resposta da criação.

Chave por módulo. SLACK_CREDENTIAL_MASTER_KEY é distinta de CALENDAR_CREDENTIAL_MASTER_KEY, EMAIL_CREDENTIAL_MASTER_KEY e das demais. Comprometer uma não entrega as outras. O custo é operacional: rotacionar invalida todas as conexões, porque não há versionamento de chave nem recifragem gradual. Rotação é evento planejado com reconexão de todos os usuários.

O escopo do token limita o alcance, e isso é a garantia mais forte. O fluxo pede user_scope, não bot token. Um token de usuário alcança apenas as DMs daquele usuário e os canais em que ele já está. Não existe caminho técnico para ler conversa privada de terceiros no workspace, mesmo com o token em mãos.

Que conteúdo de mensagem é armazenado. Nenhum. Não há tabela de mensagem no schema slack. O texto atravessa o processo — chega no evento, passa pelo filtro, é publicado no barramento e entregue — sem persistência neste building block. O que fica no banco é:

Onde o conteúdo pode ficar retido, então. No Webhooks Engine, cujo log de entrega guarda o payload — e o payload carrega o texto da mensagem. Se a sua política proíbe reter conteúdo de conversa fora do Slack, essa é a política de retenção a definir, e ela é do Webhooks Engine, não daqui.

LGPD. Mensagem é dado pessoal, e o conteúdo pode ser sensível — conversa de RH, discussão jurídica, dado de saúde num canal de benefícios. Cinco pontos:

1. Base legal e finalidade. O consentimento OAuth do usuário no Slack não é a base legal do seu tratamento. Documente a finalidade e peça só os escopos que usa.
2. O administrador do workspace é parte interessada. Em workspace corporativo com aprovação de app ligada, o administrador aprova a instalação — e essa aprovação é parte do registro de conformidade do seu cliente.
3. Minimização por filtro. O filtro de ruído reduz o que sai do Slack. É controle de privacidade além de controle de custo: mensagem descartada não trafega, não é entregue e não é logada.
4. Minimização por não armazenar. Nenhum conteúdo é persistido aqui. Preserve isso: não crie cache de mensagem sem revisar retenção.
5. Eliminação. Não há endpoint de desconexão (§15). Remover uma conexão exige intervenção no banco, e isso não revoga o token no Slack — a autorização segue ativa até o usuário removê-la na conta dele. Atender pedido de eliminação exige os dois passos, manualmente.

Autenticação e permissões.

Não há permissão de administrador separada: quem tem SLACK_WRITE cria dispatcher, e dispatcher define para onde o conteúdo do workspace é entregue. Trate SLACK_WRITE como permissão elevada ao montar os papéis.

---

Este building block está em alpha. A lista abaixo é longa de propósito.

---

Isso está pronto para produção?

Não como produto completo. O caminho principal — conectar, ingerir com filtro, entregar por webhook, enviar mensagem — funciona e é coberto por testes unitários. O que falta é ciclo de vida: desconectar, listar e apagar dispatcher, renovar token, responder em thread. Para um piloto controlado, com um cliente e acompanhamento, dá para usar. Para vender como capacidade fechada, leia a §15 inteira antes.

Vocês guardam as mensagens do meu Slack?

Neste building block, não. Não existe tabela de mensagem. O texto atravessa o processo e é entregue ao seu endpoint sem ser persistido aqui. Mas o log de entrega do Webhooks Engine guarda o payload, e o payload tem o texto. Se conteúdo de conversa não pode ficar retido fora do Slack, a política de retenção a definir é a de lá.

O app consegue ler conversa privada de qualquer pessoa do workspace?

Não. O token é de usuário, e alcança as DMs daquele usuário e os canais em que ele já está. Não existe caminho técnico para ler DM de terceiros. Ainda assim, em workspace corporativo, a instalação costuma passar por aprovação do administrador — e deve mesmo.

Por que preciso de um app Slack meu se o building block já existe?

Você não precisa de um app seu: o Slack BB usa um app da plataforma, configurado por ambiente, que cada cliente instala no workspace dele. É diferente do Calendar, onde cada organização registra o próprio app OAuth. A contrapartida é que a tela de consentimento leva a marca da plataforma, e a aprovação do app junto à Slack é única e compartilhada (§15).

A mensagem aparece como bot ou como pessoa?

Como pessoa — a que instalou o app. O envio usa as_user: true com o token de usuário. Em canal operacional isso muda a taxa de leitura, e também significa que a mensagem é atribuída àquela pessoa no histórico do workspace. Deixe isso claro para quem conecta.

Recebo todas as mensagens do workspace?

Não, e é de propósito. O filtro entrega DM, grupo de DM, qualquer mensagem que mencione o usuário conectado, e canais comuns só se estiverem em watchedChannels. Mensagem de bot, editada, apagada e de entrada ou saída de canal é descartada antes de qualquer entrega. O diagrama da decisão está em §8.

Consigo responder dentro da thread?

Hoje não. O POST /messages/send não aceita thread_ts e a resposta vai para o canal (§15). Se thread é requisito, é bloqueante — planeje em torno disso ou aguarde.

Como sei se o dispatcher está entregando?

Pelo Webhooks Engine, que guarda o log com status, código HTTP e tentativas. Este building block não expõe rota de log de entrega (§15). Para saber se o problema é antes da entrega, os logs em debug do serviço dizem quando um evento foi filtrado ou quando não havia dispatcher ativo.

Qual a diferença entre este BB e o WPP?

O canal, e o grau de maturidade. O WPP fala WhatsApp por Baileys, o WPP Business fala WhatsApp pela Meta Cloud API, e este fala Slack. Os três entregam pelo mesmo Webhooks Engine, com a mesma semântica de assinatura e retry — por isso um consumidor serve para os três. O Slack é a versão mínima do padrão: um modo de dispatcher, sem condições JSONPath, sem listar ou apagar dispatcher, sem retentativa manual. A tabela de diferenças está em §12.

O que acontece se eu rotacionar a SLACK_CREDENTIAL_MASTER_KEY?

Todas as conexões param de decifrar, com Failed to decrypt Slack token, e todos os usuários precisam reconectar. Não há versionamento de chave nem recifragem gradual. Guarde a chave em SOPS e trate como segredo de longa duração.

Por que a rota tem slack duas vezes?

Porque o app usa basePath('/slack') e os routers são montados sob /api/v1/slack. A rota efetiva é /slack/api/v1/slack/events. Atenção especial nessa: é a Request URL que você cadastra no console do Slack, e errar o prefixo é a causa mais comum de a verificação de URL falhar.

---

_{Padrão: PADRAO-DOCUMENTACAO.md · Índice: INDEX.md · Runbook: docs/slack/SETUP.md}