Integracao Linear com encurtador de URL - criacao automatica de tickets em alertas

O Linear passou para Live no catalogo de integracoes do Elido em 22-05-2026. O primeiro evento que lancamos foi broken_link_hook - quando nosso scanner encontra um link curto inativo, ele cria um issue no Linear na equipe que voce escolheu no momento da conexao, com metricas de cliques no corpo e labels roteados por tag. Este post e o guia tecnico do engenheiro: como funciona a autenticacao, como e o payload JSON e como estendemos o mesmo pipeline para picos de limite de cliques para que o plantao receba um ticket em vez de um alerta as 3 da manha.

Se voce mantém centenas ou milhares de links curtos em producao, ja conhece o modo de falha. O marketing muda o destino de uma campanha, o novo URL retorna 404 e ninguem percebe ate um cliente publicar uma captura de tela do link quebrado no Bluesky. O Linear e onde sua equipe ja faz o triage de bugs, portanto e la que colocamos o ticket.

Conectando o Linear via Personal API Key

A integracao do Linear usa uma Personal API Key, nao OAuth. Fizemos essa escolha por tres razoes: as API Keys tem escopo para o workspace, sobrevivem melhor a mudancas de administrador do que tokens OAuth vinculados a um unico usuario, e a documentacao API: Authentication do Linear as recomenda explicitamente para jobs servidor a servidor.

Gere a chave no Linear: Configuracoes, API, Personal API keys, Criar chave. Nomeie-a elido-integration para poder revoga-la depois sem precisar adivinhar. Copie a chave (ela comeca com lin_api_) e cole-a no cartao de integracao do Linear no dashboard do Elido.

O que acontece a seguir: fazemos uma query viewer para validar a chave, depois uma query teams para preencher o seletor de equipe. Voce seleciona uma equipe padrao. Essa escolha grava uma linha em integration_configs no Postgres, incluindo o team ID atribuido pelo Linear. Se voce tiver varias equipes, pode adicionar roteamento por tag na mesma tela - mais detalhes abaixo.

POST /v1/workspaces/:id/integrations/linear/connect
{
  "api_key": "lin_api_<redacted>",
  "default_team_id": "TEAM_a1b2c3",
  "default_priority": 2,
  "labels": ["short-link", "auto-filed"]
}

Por tras dos panos, o servico api-core armazena a chave criptografada em repouso usando o esquema de criptografia por envelope do ADR-0036. A chave descriptografada so existe na memoria durante a chamada GraphQL real. Nunca registramos o valor bruto e a UI de logs de integracao mostra apenas os ultimos 4 caracteres.

Um aviso importante: as Personal API Keys do Linear estao vinculadas ao usuario que as criou. Se esse usuario sair da empresa e voce desativar o assento Linear dele, a chave morre com ele. A melhor pratica e criar um usuario de servico no Linear (usamos [email protected]) e gerar a chave a partir dessa conta.

O evento broken_link_hook - o que o dispara e o que contem

Nosso servico url-scanner executa um rastreamento semanal de todos os links curtos ativos no seu workspace. Para cada link, ele faz um HTTP HEAD no destino, depois um GET se HEAD nao for suportado, e em seguida valida a cadeia TLS. Quatro condicoes ativam o estado de link quebrado:

1. HTTP 4xx ou 5xx em duas sondagens consecutivas (dupla verificacao para absorver 500s transitorios)
2. TLS expirado ou autoassinado onde era valido na semana anterior
3. DNS NXDOMAIN - o host de destino nao resolve mais
4. Correspondencia de impressao digital de dominio estacionado - o destino resolve mas o corpo da resposta corresponde a um template de squatter conhecido (mantemos um pequeno conjunto de impressoes digitais)

Quando qualquer uma dessas quatro ocorre, o scanner publica um evento link.broken no Redpanda. O webhook-dispatcher o consome, verifica suas integracoes ativas e para o Linear materializa o payload abaixo.

Aqui esta um payload real de broken_link_hook capturado do nosso ambiente de staging (alguns campos omitidos):

{
  "event": "link.broken",
  "link_id": "01J9V7QXMZ8K2Y3N4P5R6T7W8Z",
  "short_url": "https://s.elido.me/spring-launch",
  "destination_url": "https://oldcampaign.example.com/landing",
  "failure_type": "http_5xx",
  "failure_detail": "502 Bad Gateway, 2 consecutive probes",
  "last_working_at": "2026-05-28T14:22:00Z",
  "detected_at": "2026-06-04T03:11:42Z",
  "clicks_last_7d": 2841,
  "clicks_last_24h": 412,
  "top_referrers": [
    { "host": "linkedin.com", "clicks": 1203 },
    { "host": "twitter.com", "clicks": 488 },
    { "host": "direct", "clicks": 612 }
  ],
  "tags": ["campaign-spring-2026", "paid"],
  "owner_email": "[email protected]"
}

O adaptador Linear em services/api-core/internal/integrations/linear/broken_link_hook.go pega esse payload e constroi uma mutacao GraphQL contra a Issues API do Linear. O titulo do issue segue um padrao fixo para que o plantao possa busca-lo com grep:

[Elido] Broken link: /spring-launch (502 Bad Gateway)

O corpo e Markdown estruturado com cinco secoes: detalhes do link, ultimo timestamp funcional, delta de cliques em relacao a baseline de 7 dias, os tres principais referrers e um bloco de correcao sugerida. O bloco de correcao verifica failure_type e escolhe uma sugestao predefinida - para http_5xx, "Verifique se o destino esta aplicando rate limit ou em deploy"; para parked_domain, "O dominio pode ter expirado ou sido ocupado, arquive este link"; e assim por diante.

Labels sao atribuidos de duas fontes: seu conjunto de labels padrao (configurado na conexao) e labels dinamicos derivados da lista de tags. Se uma tag corresponder a paid ou organic, adicionamos como label para que os PMs possam filtrar suas views no Linear.

Deduplicacao, rate limits e dead-letter queue

Deduplicamos os eventos broken_link_hook por host de destino durante 24 horas. Se oldcampaign.example.com caiu e 800 links curtos apontam para ele, voce recebe um unico ticket no Linear com todos os 800 URLs curtos listados no corpo, nao 800 tickets separados. Foi uma licao dura da beta inicial - o primeiro cliente a encontrar um dominio inativo foi soterrado.

O endpoint GraphQL do Linear tem um rate limit global por workspace. Nosso webhook-dispatcher rastreia o header Retry-After e usa backoff exponencial com full jitter, ate cinco tentativas. Apos cinco, o evento vai para uma dead-letter queue. Voce pode ver as entradas da DLQ em Configuracoes, Integracoes, Linear, Eventos com falha, e reproduzir qualquer uma com um clique. A DLQ tambem e exposta pela funcionalidade de webhooks para reproducao programatica.

Limite de cliques e gatilhos personalizados

O mesmo adaptador Linear consome eventos click_threshold_hook. Voce define limites por link ou por campanha no dashboard do Elido, e criamos um issue no Linear quando um link cruza uma faixa. Dois tipos de faixa sao suportados hoje:

• Spike: cliques na ultima hora excedem N vezes a baseline horaria dos ultimos 7 dias (N padrao e 3). Util para detectar viralidade ou, menos agradavelmente, trafego de bots.
• Cliff: cliques na ultima hora caem abaixo de 10% da baseline. Util para detectar campanhas inativas - se um anuncio pago foi pausado na origem, voce ve o ticket no Linear antes do standup de marketing.

Aqui esta um payload click_threshold_hook:

{
  "event": "link.click_threshold",
  "link_id": "01J9V7QXMZ8K2Y3N4P5R6T7W8Z",
  "short_url": "https://s.elido.me/spring-launch",
  "band": "spike",
  "current_hour_clicks": 8421,
  "baseline_hourly_clicks": 612,
  "multiplier": 13.76,
  "top_referrers": [
    { "host": "news.ycombinator.com", "clicks": 6203 },
    { "host": "direct", "clicks": 1488 }
  ],
  "tags": ["campaign-spring-2026"],
  "triggered_at": "2026-06-04T11:14:00Z"
}

Para um spike, o bloco de correcao diz: "Verifique se e trafego organico, nao uma campanha de spoofing de referrers. Confira o detalhamento de referrers acima." Para um cliff: "Confirme se a campanha ainda esta ativa na origem. Se foi pausada, arquive este link."

Roteamento por tag entre multiplas equipes

O seletor de equipe padrao e suficiente para um workspace de 20 pessoas. Para organizacoes maiores, voce quer que um ticket no Linear sobre um link de marketing va para a equipe de Marketing, e um ticket sobre um link de docs va para a equipe de Documentacao. O roteamento por tag cuida disso.

As regras de roteamento ficam em integration_configs.routing_json e sao avaliadas de cima para baixo. Uma regra tem esta forma:

[
  {
    "tag_glob": "campaign-*",
    "team_id": "TEAM_growth",
    "labels": ["growth", "urgent"]
  },
  { "tag_glob": "docs-*", "team_id": "TEAM_docs", "labels": ["docs"] },
  {
    "tag_glob": "internal-*",
    "team_id": "TEAM_internal",
    "labels": ["internal"]
  },
  { "default": true, "team_id": "TEAM_a1b2c3" }
]

A primeira regra cujo glob corresponde a pelo menos uma tag no link ganha. Se nada corresponder, a regra padrao pega o evento. A sintaxe de glob e a mesma dos filtros de views salvas do Linear, que os PMs ja conhecem.

Voce tambem pode rotear por failure_type. Algumas equipes querem que todas as falhas de TLS va para a equipe de plataforma, pois geralmente indicam configuracao incorreta de certificado em um dominio personalizado de tenant. Adicione uma regra com chave failure_type: tls_expired e pronto.

Gatilhos personalizados via webhooks

Nem todas as equipes querem criar tickets no Linear para cada tipo de evento que publicamos. O catalogo completo de eventos esta documentado na pagina da funcionalidade de webhooks, mas as combinacoes comuns que as equipes configuram ao lado do Linear sao:

• link.created para uma equipe Linear para auditorias de novos links (raro, geralmente para equipes de compliance)
• domain.takeover_detected para surpresas de TLS em dominios personalizados
• link.scan_complete para tickets de resumo semanal (um issue por execucao de scan, listando todos os links sinalizados)

Se o evento que voce quer nao esta no catalogo, pode construir o seu proprio usando o destino webhook generico e nosso guia de observabilidade. Ou simplesmente envie uma solicitacao de funcionalidade no nosso board publico do Linear - meta mas recursivo.

Precos e o que voce obtem em cada plano

A integracao do Linear esta incluida no tier Pro e acima. No Free, voce pode conectar o Linear mas so obtem broken_link_hook (sem limite de cliques ou gatilhos personalizados). Consulte a pagina de precos para a matriz completa. Se voce e uma equipe maior considerando isso por razoes de compliance - digamos, o Artigo 32 do RGPD exige que voce detecte vazamentos de dados de redirecionamentos quebrados apontando para dominios de squatters - a pagina de solucoes Enterprise cobre o que oferecemos em escala.

Leituras relacionadas

• Webhooks para eventos de link: guia do desenvolvedor - o barramento de eventos subjacente que alimenta todas as integracoes, incluindo o Linear.
• Conectando o Sentry em 12 servicos Go - como monitoramos o dispatcher que dispara os eventos do Linear, para saber quando o proprio dispatcher esta com problemas.
• Estrategia de prevencao de link rotting - a historia operacional mais ampla por tras do motivo pelo qual construimos a deteccao de links quebrados.

O catalogo completo de integracoes lista 43 fornecedores em junho de 2026, com o Linear entre os 20 ativos. Se sua equipe usa Jira em vez disso, esse adaptador esta em beta - envie um email e ativaremos voce.