Linear pasó a Live en el catálogo de integraciones de Elido el 22-05-2026. El primer evento que lanzamos fue broken_link_hook - cuando nuestro scanner encuentra un enlace corto muerto, crea un issue de Linear en el equipo que elegiste al conectar, con métricas de clics en el cuerpo y etiquetas enrutadas por tag. Este post es el recorrido técnico del ingeniero: cómo funciona la autenticación, cómo luce el payload JSON y cómo extendimos la misma tubería a los picos de umbral de clics para que el equipo de guardia reciba un ticket en lugar de una alerta a las 3 de la madrugada.
Si mantienes cientos o miles de enlaces cortos en producción, ya conoces el modo de fallo. Marketing cambia el destino de una campaña, la nueva URL devuelve 404, y nadie se da cuenta hasta que un cliente publica una captura de pantalla del enlace muerto en Bluesky. Linear es donde tu equipo ya triagea bugs, así que ahí es donde ponemos el ticket.
Conectar Linear con Personal API Key
La integración de Linear usa una Personal API Key, no OAuth. Tomamos esa decisión por tres razones: las API Keys tienen alcance al workspace, sobreviven mejor a los cambios de administrador que los tokens OAuth vinculados a un único usuario, y la documentación de API: Authentication de Linear las recomienda explícitamente para trabajos servidor a servidor.
Genera la clave en Linear: Configuración, API, Personal API keys, Crear clave. Nómbrala elido-integration para poder revocarla después sin adivinar. Copia la clave (empieza con lin_api_) y pégala en la tarjeta de integración de Linear en el dashboard de Elido.
Lo que ocurre a continuación: hacemos una consulta viewer para validar la clave, luego una consulta teams para rellenar el selector de equipo. Seleccionas un equipo predeterminado. Esa elección escribe una fila en integration_configs en Postgres, incluyendo el team ID que Linear asignó. Si tienes varios equipos, puedes añadir enrutamiento por etiquetas en la misma pantalla - más sobre eso a continuación.
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 detrás, el servicio api-core almacena la clave cifrada en reposo mediante el esquema de cifrado por envolvente del ADR-0036. La clave descifrada solo existe en memoria durante la llamada GraphQL real. Nunca registramos el valor en bruto, y la UI de logs de integración muestra solo los últimos 4 caracteres.
Un detalle importante: las Personal API Keys de Linear están vinculadas al usuario que las creó. Si ese usuario abandona tu empresa y desactivas su cuenta de Linear, la clave muere con él. La buena práctica es crear un usuario de tipo servicio en Linear (nosotros usamos [email protected]) y generar la clave desde esa cuenta.
El evento broken_link_hook - qué lo dispara y qué hay en el cuerpo
Nuestro servicio url-scanner ejecuta un rastreo semanal de todos los enlaces cortos activos en tu workspace. Para cada enlace, hace un HTTP HEAD en el destino, luego un GET si HEAD no está soportado, y después valida la cadena TLS. Cuatro condiciones activan el estado de enlace roto:
- HTTP 4xx o 5xx en dos sondeos consecutivos (doble comprobación para absorber 500s transitorios)
- TLS expirado o autofirmado donde era válido la semana anterior
- DNS NXDOMAIN - el host de destino ya no resuelve
- Coincidencia de fingerprint de dominio aparcado - el destino resuelve pero el cuerpo de la respuesta coincide con una plantilla conocida de squatter (mantenemos un pequeño conjunto de fingerprints)
Cuando cualquiera de esas cuatro se activa, el scanner publica un evento link.broken en Redpanda. El webhook-dispatcher lo consume, busca tus integraciones activas y para Linear materializa el payload siguiente.
Aquí hay un payload real de broken_link_hook capturado de nuestro entorno de staging (algunos 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]"
}
El adaptador de Linear en services/api-core/internal/integrations/linear/broken_link_hook.go toma ese payload y construye una mutación GraphQL contra la Issues API de Linear. El título del issue sigue un patrón fijo para que el equipo de guardia pueda buscarlo con grep:
[Elido] Broken link: /spring-launch (502 Bad Gateway)
El cuerpo es Markdown estructurado con cinco secciones: detalles del enlace, última marca de tiempo funcional, delta de clics respecto a la línea base de 7 días, los tres principales referrers y un bloque de solución sugerida. El bloque de solución mira failure_type y elige una sugerencia predefinida - para http_5xx, "Verifica si el destino está aplicando rate limit o en proceso de despliegue"; para parked_domain, "El dominio puede haber expirado o sido capturado, archiva este enlace"; y así sucesivamente.
Las etiquetas se asignan desde dos fuentes: tu conjunto de etiquetas predeterminado (configurado al conectar) y etiquetas dinámicas derivadas de la lista de tags. Si un tag coincide con paid u organic, lo añadimos como etiqueta para que los PMs puedan filtrar sus vistas en Linear.
Deduplicación, rate limits y la dead-letter queue
Deduplicamos los eventos broken_link_hook por host de destino durante 24 horas. Si oldcampaign.example.com cayó y 800 enlaces cortos apuntan a él, recibes un único ticket de Linear con los 800 URLs cortos listados en el cuerpo, no 800 tickets separados. Fue una dura lección de la beta temprana - el primer cliente que encontró un dominio muerto quedó enterrado.
El endpoint GraphQL de Linear tiene un rate limit global por workspace. Nuestro webhook-dispatcher rastrea el header Retry-After y usa backoff exponencial con full jitter, hasta cinco intentos. Tras cinco, el evento llega a una dead-letter queue. Puedes ver las entradas de la DLQ en Configuración, Integraciones, Linear, Eventos fallidos, y reproducir cualquiera con un clic. La DLQ también está disponible a través de la función de webhooks para reproducción programática.
Umbral de clics y disparadores personalizados
El mismo adaptador de Linear consume eventos click_threshold_hook. Defines umbrales por enlace o por campaña en el dashboard de Elido, y creamos un issue de Linear cuando un enlace cruza una banda. Hoy se soportan dos tipos de banda:
- Spike: los clics en la última hora superan N veces la línea base horaria móvil de 7 días (N por defecto es 3). Útil para detectar viralidad o, menos agradablemente, tráfico de bots.
- Cliff: los clics en la última hora caen por debajo del 10% de la línea base móvil. Útil para detectar campañas muertas - si se pausó un anuncio de pago en el origen, ves el ticket de Linear antes del standup de marketing.
Aquí hay un payload de 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 un spike, el bloque de solución dice: "Verifica si es tráfico orgánico, no una campaña de spoofing de referrers. Comprueba el desglose de referrers arriba." Para un cliff: "Confirma que la campaña sigue activa en el origen. Si fue pausada, archiva este enlace."
Enrutamiento por etiquetas entre varios equipos
El selector de equipo predeterminado es suficiente para un workspace de 20 personas. En organizaciones más grandes, quieres que un ticket de Linear de un enlace de marketing vaya al equipo de Marketing, y que un ticket de un enlace de documentación vaya al equipo de Documentación. El enrutamiento por etiquetas lo gestiona.
Las reglas de enrutamiento viven en integration_configs.routing_json y se evalúan de arriba hacia abajo. Una regla tiene este aspecto:
[
{
"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" }
]
La primera regla cuyo glob coincida con al menos una etiqueta del enlace gana. Si nada coincide, la regla predeterminada toma el evento. La sintaxis de glob es la misma que los filtros de vistas guardadas de Linear, así que los PMs ya la conocen.
También puedes enrutar por failure_type. Algunos equipos quieren que todos los fallos de TLS vayan al equipo de plataforma ya que suelen indicar una mala configuración del certificado en un dominio personalizado de un tenant. Añade una regla con failure_type: tls_expired y listo.
Disparadores personalizados mediante webhooks
No todos los equipos quieren crear tickets de Linear para cada tipo de evento que publicamos. El catálogo completo de eventos está documentado en la página de la función de webhooks, pero las combinaciones más comunes que los equipos configuran junto a Linear son:
link.createda un equipo de Linear para auditorías de nuevos enlaces (raro, generalmente para equipos de compliance)domain.takeover_detectedpara sorpresas de TLS en dominios personalizadoslink.scan_completepara tickets de resumen semanal (un issue por ejecución de escaneo, listando todos los enlaces marcados)
Si el evento que necesitas no está en el catálogo, puedes construir el tuyo propio usando el webhook genérico y nuestra guía de observabilidad. O simplemente abre una solicitud de funcionalidad en nuestro tablero público de Linear - meta pero recursivo.
Precios y qué obtienes en cada plan
La integración de Linear está incluida en el tier Pro y superiores. En Free, puedes conectar Linear pero solo obtienes broken_link_hook (sin umbral de clics ni disparadores personalizados). Consulta la página de precios para la matriz completa. Si eres un equipo grande que considera esto por razones de compliance - por ejemplo, el artículo 32 del RGPD te exige detectar fugas de datos a través de redirecciones rotas que apuntan a dominios squatter - la página de soluciones Enterprise cubre lo que ofrecemos a escala.
Lectura relacionada
- Webhooks para eventos de enlace: guía para desarrolladores - el bus de eventos subyacente que impulsa todas las integraciones, incluida Linear.
- Conectando Sentry en 12 servicios Go - cómo monitorizamos el dispatcher que dispara los eventos de Linear, para saber cuándo el propio dispatcher falla.
- Estrategia de prevención de link rotting - la historia operativa más amplia detrás del motivo por el que construimos la detección de enlaces rotos.
El catálogo de integraciones completo lista 43 proveedores a junio de 2026, con Linear entre los 20 activos. Si tu equipo usa Jira en su lugar, ese adaptador está en beta - escríbenos y te activamos.
Preguntas frecuentes
¿Cómo se autentica Elido con Linear?
Usamos una Personal API Key con alcance al workspace, no OAuth. Generas la clave en Linear en Configuración, API, y luego la pegas en la tarjeta de integración de Elido. La clave nunca sale de nuestro vault, y la ocultamos en los logs. Si la rotas, el siguiente evento activa una solicitud suave de reautenticación en lugar de fallar silenciosamente.
¿Qué cuenta exactamente como enlace roto en el evento broken_link_hook?
Nuestro url-scanner rastrea cada enlace corto activo semanalmente y marca cuatro condiciones: HTTP 4xx o 5xx en dos sondeos consecutivos, certificado TLS expirado o no verificable, DNS NXDOMAIN y fingerprints conocidos de dominios aparcados. Cualquiera de esas cuatro crea un único issue de Linear, deduplicado por host de destino durante 24 horas para que un dominio muerto no genere 800 tickets.
¿Puedo enviar issues a distintos equipos de Linear según las etiquetas del enlace?
Sí. En la pantalla de conexión seleccionas un equipo predeterminado y luego añades reglas de enrutamiento - por ejemplo, las etiquetas que coincidan con campaign-* van al equipo de Growth, mientras que las que coincidan con docs-* van a Ingeniería. Las reglas se evalúan de arriba hacia abajo con un fallback predeterminado. El conjunto de reglas vive en Postgres, así que puedes auditar los cambios a través del historial de administración.
¿Esto funciona también para alertas de umbral de clics, no solo para enlaces rotos?
Sí, desde la Fase 12. El mismo adaptador de Linear consume eventos click_threshold_hook junto a broken_link_hook. Defines umbrales por enlace o por campaña en el dashboard de Elido, y creamos un issue de Linear cuando un enlace cruza una banda - ya sea un pico (3x la línea base en una hora) o un desplome (caída por debajo del 10% de la línea base).
¿Qué ocurre si Linear aplica rate limit a la integración?
El endpoint GraphQL de Linear devuelve un 429 con un header Retry-After. Nuestro webhook-dispatcher lo respeta con backoff exponencial hasta cinco intentos, luego aparca el evento en una dead-letter queue. Puedes ver las entradas de la DLQ en Configuración, Integraciones, Linear, Eventos fallidos, y reproducir cualquiera con un clic. La DLQ también está disponible a través de la GraphQL API en /v1/integrations/linear/dlq. Todavía no hemos visto un 429 sostenido de Linear en producción.
Prueba Elido
Pega una URL, obtén un enlace corto
Sin registro. El enlace vive 30 días. Crea una cuenta para conservarlo.
Gratis, sin registro · 2 por día