Bot encurtador de URL para Slack: encurte links e roteie alertas

O Slack já tomou conta da superfície de chat do seu time - que ele também encurte os seus links. O app Elido para Slack faz duas coisas: dá a cada membro um comando slash /shorten e roteia alertas de eventos de link para os canais que você escolher. A instalação leva cerca de 90 segundos. Nenhum código de handler de webhook, nenhum Bolt SDK, nenhum túnel ngrok.

Este artigo percorre as três partes em jogo: o fluxo do comando slash, a matriz de roteamento de alertas e o mecanismo de assinatura HMAC que impede requisições POST aleatórias de se passarem pelo Slack. Se você quiser entender a superfície de webhooks mais ampla que alimenta esses alertas, o artigo webhooks para eventos de link documenta cada payload que a Elido emite. O app Slack é uma das integrações pré-construídas que consome esses eventos por você.

O comando slash /shorten

Um usuário digita isso em qualquer canal:

/shorten https://blog.elido.app/post/launch-2026?utm_source=announce

O Slack envia um POST assinado para https://api.elido.app/integrations/slack/commands. O corpo é application/x-www-form-urlencoded (o Slack ainda usa codificação de formulário para comandos slash, não JSON - o que pega todo mundo de surpresa na primeira vez). Os campos relevantes são:

team_id=T01ABCD2EF
channel_id=C01234ABCDE
user_id=U01HJKLMNOP
command=/shorten
text=https://blog.elido.app/post/launch-2026?utm_source=announce
response_url=https://hooks.slack.com/commands/T01ABCD2EF/...

A Elido busca a linha OAuth pelo team_id, encontra o ID do workspace contra o qual foi instalada, cria um shortlink no domínio padrão do workspace e retorna uma mensagem efêmera em menos de 200ms no p95. A resposta é efêmera por padrão para que o canal não seja bombardeado toda vez que alguém encurta uma URL durante uma reunião.

Se quem invocou o comando quiser uma mensagem pública, passa --public como último token:

/shorten --public https://launch.elido.app

Três escopos OAuth são necessários na instalação: commands (para que o comando slash possa ser invocado), chat:write (para que a Elido possa postar mensagens de acompanhamento com botões de cópia) e incoming-webhook (para que os alertas cheguem ao canal escolhido pelo instalador). A referência de Slash Commands do Slack lista o conjunto completo, mas esses três cobrem tudo o que a Elido faz. Domínios personalizados são respeitados: se o seu workspace tem go.acme.com configurado via domínios personalizados, o /shorten cria shortlinks nesse host.

Uma nota sobre orçamentos de latência. O Slack dá aos comandos slash 3000ms de tempo real para responder. A Elido responde em 180-220ms p95 nos POPs de edge da UE e dos EUA porque o handler do comando slash usa o mesmo cache de caminho rápido que o redirect de edge. Se o seu time está na APAC e você vê valores acima de 350ms, verifique o roteamento regional de POPs em /docs/guides/observability.

Alertas de canal impulsionados por gatilhos de eventos

A outra metade do app Slack é o roteamento de alertas. Você escolhe um tipo de evento, escolhe um canal e recebe uma notificação. Os quatro tipos de evento disponíveis hoje:

• broken-link: o destino retornou 4xx ou 5xx no último crawl do scanner de links
• click-threshold: os cliques ultrapassaram um limiar salvo (padrão: 100 em uma janela deslizante de 5 minutos)
• scan-failure: o scanner de URL sinalizou o destino como phishing, malware ou em uma blocklist pública
• new-conversion: uma conversão rastreada foi disparada (requer rastreamento de conversões)

O payload de alerta que a Elido encaminha para o Slack usa Block Kit, porque texto simples em um canal movimentado é ignorado. Veja como fica um alerta click-threshold no fio quando a Elido faz POST na URL do incoming-webhook do Slack:

{
  "text": "click-threshold crossed on go.acme.com/launch",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": ":chart_with_upwards_trend: Click threshold crossed"
      }
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Link:*\n<https://go.acme.com/launch|go.acme.com/launch>"
        },
        { "type": "mrkdwn", "text": "*Window:*\n5m" },
        { "type": "mrkdwn", "text": "*Clicks:*\n412" },
        { "type": "mrkdwn", "text": "*Threshold:*\n100" }
      ]
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": { "type": "plain_text", "text": "Open dashboard" },
          "url": "https://app.elido.app/links/abc123"
        }
      ]
    }
  ]
}

Um alerta scan-failure é semelhante, mas usa :rotating_light: e inclui a categoria de ameaça do scanner: phishing, malware, spam ou blocklist. Um alerta broken-link traz o código de status HTTP e o timestamp do último estado funcional conhecido - a primeira pergunta que a pessoa de plantão faz.

O roteamento é por workspace e por evento. Uma configuração típica para um time de growth de 30 pessoas:

Você configura isso no painel de configurações da integração com o Slack. Cada rota é uma linha no Postgres - sem YAML, sem arquivo de configuração JSON, sem redeploy. O mesmo motor de roteamento alimenta as integrações com o Linear e o Pipedrive, então o modelo mental se transfere se você usa ambos.

Se quiser que os alertas cheguem a múltiplos destinos, espelhe o mesmo evento para uma assinatura de webhook genérica e roteie o JSON para onde precisar. Esse padrão está documentado em automação de encurtador de URL com Zapier para o público no-code.

Verificação HMAC e a armadilha da reinstalação

O Slack assina cada requisição de entrada para o seu endpoint de comando slash. A assinatura é HMAC SHA256 sobre uma string que o Slack constrói a partir da versão, do timestamp e do corpo bruto da requisição. O procedimento está no guia de verificação de requisições do Slack. O verificador da Elido em Go se parece com isso:

func verifySlackSignature(secret, ts, body, sig string) error {
    // Reject anything older than 5 minutes to block replays.
    age := time.Since(parseTs(ts))
    if age > 5*time.Minute || age < -1*time.Minute {
        return errReplay
    }
    base := fmt.Sprintf("v0:%s:%s", ts, body)
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(base))
    expected := "v0=" + hex.EncodeToString(mac.Sum(nil))
    if !hmac.Equal([]byte(expected), []byte(sig)) {
        return errBadSig
    }
    return nil
}

Três coisas dão errado aqui, em ordem de frequência:

1. O corpo é parseado antes da assinatura. Se o seu framework HTTP chamar r.ParseForm() antes de você ler o corpo bruto, o corpo some e a assinatura nunca vai bater. Leia r.Body primeiro, depois faça o parse. O handler de comando slash da Elido lê o corpo em um buffer e o re-parseia, o que custa uma alocação de memória e economiza uma semana de depuração.

2. Drift de relógio no timestamp. A janela de replay recomendada pelo Slack é de 5 minutos. Se o relógio do seu servidor derivar mais do que isso (comum em bare-metal sem chrony), toda requisição assinada parece um replay. Execute chronyc tracking no servidor e confirme Leap status: Normal.

3. Reinstalação com signing secret rotacionado. Esse é o que te acorda de madrugada. Se você rotacionar o signing secret no painel do app Slack (Basic Information > Signing Secret > Regenerate), todas as instalações OAuth existentes em todos os workspaces começam imediatamente a falhar na verificação de assinatura. O administrador do workspace precisa reinstalar o app para obter um novo handshake. Não há rotação silenciosa - o Slack não propaga o novo segredo para as instalações existentes.

O raio de explosão depende do seu modelo de distribuição. Se o seu app Slack é de workspace único (app interno da sua empresa), a rotação é uma reinstalação de 90 segundos por um único administrador. Se o seu app está no diretório público do Slack e 4000 workspaces o instalaram, você acabou de bloquear todos eles. Escolha as janelas de rotação de acordo e anuncie no changelog com pelo menos 48 horas de antecedência.

Um modo de falha relacionado: instalar o mesmo app Slack em um workspace diferente usando a mesma sessão do navegador. O Slack às vezes retorna um token vinculado ao time errado quando os cookies são persistentes. A solução é uma janela privada ou ?ignore_session=1 na URL de instalação. O fluxo de instalação da Elido em /dashboard/integrations/slack já passa essa flag porque nos queimamos no início da Beta.

Quando o bot do Slack não é a resposta certa

O Slack é ótimo para alertas com intervenção humana. É o destino errado para eventos programáticos de alto volume. Se você gerar mais de ~20 eventos por minuto, o Slack limita o endpoint de incoming-webhook a aproximadamente 1 mensagem por segundo por canal, e você perderá alertas. Roteie-os para uma métrica do Datadog ou um consumidor de webhook bruto, e encaminhe para o Slack apenas o resumo do cruzamento de limiar.

O outro caso em que o Slack é a escolha errada: trilhas de auditoria de conformidade. As mensagens do Slack são mutáveis (você pode editá-las e excluí-las) e a política de retenção é controlada pelo workspace. Se o seu auditor precisar de um log imutável de quem encurtou qual link e quando, envie os eventos do comando slash para o seu data warehouse via exportação do ClickHouse e trate o Slack apenas como camada de notificação.

Para times de growth que roteiam alertas de cliques de campanha, o bot do Slack cobre 95% do que as pessoas pedem em /solutions/marketers. Para times de plataforma que usam nossa API + SDKs, é um dos vários destinos para os quais você pode fazer fan-out.

Preços e limites

A integração com o Slack está disponível em todos os planos, incluindo o gratuito. Não há cobrança por mensagem - o limite é nos próprios shortlinks e cliques, que você pode verificar na página de preços. Cada workspace pode configurar até 32 regras de roteamento (combinações de tipo de evento x canal), mais do que qualquer time com quem conversei chegou a usar.

Instalações self-hosted da Elido também funcionam. Você aponta a URL de requisição do app Slack para o seu próprio domínio, define o signing secret no ambiente do api-core e o restante é idêntico. Os docs de self-host cobrem as variáveis de ambiente; o guia de observabilidade cobre os nomes das métricas para que você possa graficar a latência dos comandos slash e a taxa de sucesso na entrega de alertas no Grafana ou Datadog.

O que fazer a seguir

Se você já usa a Elido, abra /dashboard/integrations/slack, clique em Conectar, escolha um canal padrão para cada tipo de evento e mãos à obra. A instalação realmente leva 90 segundos. Se você está avaliando, o catálogo de integrações lista cada conector e em qual plano está disponível, e a comparação com o Bitly mostra como a superfície do Slack se compara com os incumbentes (spoiler: o Bitly não tem comando slash).

Se você está construindo o seu próprio bot, copie o padrão HMAC acima e respeite o relógio de 3000ms. A UX de comandos slash do Slack penaliza tudo o que é lento, e um bot que parece rápido é metade do motivo pelo qual as pessoas o instalam.