Integrazione Linear con accorciatore di URL - ticket automatici sugli alert

Linear è andato Live nel catalogo delle integrazioni Elido il 22-05-2026. Il primo evento che abbiamo rilasciato era broken_link_hook - quando il nostro scanner trova un link breve non funzionante, crea un issue Linear nel team che hai scelto al momento della connessione, con le metriche di clic nel corpo e le label smistate per tag. Questo post è il walkthrough tecnico dell'ingegnere: come funziona l'autenticazione, come appare il payload JSON e come abbiamo esteso la stessa pipeline ai picchi di soglia clic in modo che chi è di turno riceva un ticket invece di una notifica alle 3 di notte.

Se gestisci centinaia o migliaia di link brevi in produzione, conosci già la modalità di errore. Il marketing cambia la destinazione di una campagna, il nuovo URL restituisce 404, e nessuno se ne accorge finché un cliente pubblica su Bluesky uno screenshot del link morto. Linear è dove il tuo team già fa il triage dei bug, quindi è lì che mettiamo il ticket.

Connettere Linear tramite Personal API Key

L'integrazione Linear usa una Personal API Key, non OAuth. Abbiamo fatto questa scelta per tre motivi: le API Key hanno scope al workspace, sopravvivono meglio ai cambi di amministratore rispetto ai token OAuth legati a un singolo utente, e la documentazione API: Authentication di Linear le raccomanda esplicitamente per i job server-to-server.

Genera la chiave in Linear: Impostazioni, API, Personal API keys, Crea chiave. Chiamala elido-integration così puoi revocarla in seguito senza dover indovinare. Copia la chiave (inizia con lin_api_) e incollala nella scheda di integrazione Linear nel dashboard Elido.

Cosa succede poi: eseguiamo una query viewer per validare la chiave, poi una query teams per popolare il selettore team. Selezioni un team predefinito. Questa scelta scrive una riga in integration_configs in Postgres, incluso il team ID assegnato da Linear. Se hai più team, puoi aggiungere il routing per tag nella stessa schermata - ne parleremo più avanti.

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"]
}

Dietro le quinte, il servizio api-core memorizza la chiave cifrata a riposo tramite lo schema di cifratura a busta dell'ADR-0036. La chiave decifrata vive in memoria solo durante la chiamata GraphQL effettiva. Non loggamo mai il valore grezzo, e la UI dei log di integrazione mostra solo gli ultimi 4 caratteri.

Un avviso importante: le Personal API Key di Linear sono legate all'utente che le ha create. Se quell'utente lascia la tua azienda e disattivi il suo account Linear, la chiave muore con lui. La best practice è creare un utente di tipo service in Linear (noi usiamo [email protected]) e generare la chiave da quell'account.

L'evento broken_link_hook - cosa lo attiva e cosa c'è nel corpo

Il nostro servizio url-scanner esegue una scansione settimanale di tutti i link brevi attivi nel tuo workspace. Per ogni link, esegue un HTTP HEAD sulla destinazione, poi un GET se HEAD non è supportato, poi valida la catena TLS. Quattro condizioni attivano lo stato di link rotto:

1. HTTP 4xx o 5xx su due probe consecutivi (doppio controllo per assorbire i 500 transitori)
2. TLS scaduto o auto-firmato dove era valido la settimana precedente
3. DNS NXDOMAIN - l'host di destinazione non risolve più
4. Corrispondenza di fingerprint di dominio parcheggiato - la destinazione risolve ma il corpo della risposta corrisponde a un template di squatter noto (manteniamo un piccolo set di fingerprint)

Quando una qualsiasi di queste quattro condizioni si verifica, lo scanner pubblica un evento link.broken su Redpanda. Il webhook-dispatcher lo consuma, cerca le tue integrazioni attive e per Linear materializza il payload seguente.

Ecco un vero payload broken_link_hook catturato dal nostro ambiente di staging (alcuni campi omessi):

{
  "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]"
}

L'adapter Linear in services/api-core/internal/integrations/linear/broken_link_hook.go prende quel payload e costruisce una mutazione GraphQL contro la Issues API di Linear. Il titolo dell'issue segue un pattern fisso in modo che chi è di turno possa trovarlo con grep:

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

Il corpo è Markdown strutturato con cinque sezioni: dettagli del link, ultimo timestamp funzionante, delta clic rispetto alla baseline a 7 giorni, i tre principali referrer e un blocco di correzione suggerita. Il blocco di correzione esamina failure_type e sceglie un suggerimento predefinito - per http_5xx, "Verifica se la destinazione sta applicando rate limit o è in fase di deploy"; per parked_domain, "Il dominio potrebbe essere scaduto o squattato, archivia questo link"; e così via.

Le label vengono assegnate da due fonti: il set di label predefinito (configurato alla connessione) e label dinamiche derivate dalla lista di tag. Se un tag corrisponde a paid o organic, lo aggiungiamo come label in modo che i PM possano filtrare le loro viste Linear.

Deduplicazione, rate limit e dead-letter queue

Deduplicchiamo gli eventi broken_link_hook per host di destinazione per 24 ore. Se oldcampaign.example.com è morto e 800 link brevi puntano a esso, ricevi un singolo ticket Linear con tutti gli 800 URL brevi elencati nel corpo, non 800 ticket separati. È stata una dura lezione dalla beta iniziale - il primo cliente che ha trovato un dominio morto è stato sommerso.

L'endpoint GraphQL di Linear ha un rate limit globale per workspace. Il nostro webhook-dispatcher traccia l'header Retry-After e usa backoff esponenziale con full jitter, fino a cinque tentativi. Dopo cinque, l'evento finisce in una dead-letter queue. Puoi vedere le voci DLQ in Impostazioni, Integrazioni, Linear, Eventi falliti, e riprodurne qualsiasi con un clic. La DLQ è esposta anche tramite la funzionalità webhooks per la riproduzione programmatica.

Soglia clic e trigger personalizzati

Lo stesso adapter Linear consuma eventi click_threshold_hook. Definisci le soglie per link o per campagna nel dashboard Elido, e creiamo un issue Linear quando un link attraversa una banda. Oggi sono supportati due tipi di banda:

• Spike: i clic nell'ultima ora superano N volte la baseline oraria mobile a 7 giorni (N di default è 3). Utile per rilevare la viralità o, meno piacevolmente, il traffico bot.
• Cliff: i clic nell'ultima ora scendono sotto il 10% della baseline mobile. Utile per rilevare campagne morte - se un annuncio a pagamento è stato messo in pausa a monte, vedi il ticket Linear prima dello standup marketing.

Ecco un 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"
}

Per un picco, il blocco di correzione recita: "Verifica che si tratti di traffico organico e non di una campagna di spoofing dei referrer. Controlla il breakdown dei referrer sopra." Per una caduta: "Conferma che la campagna sia ancora attiva a monte. Se è stata messa in pausa, archivia questo link."

Routing per tag su più team

Il selettore team predefinito va bene per un workspace di 20 persone. Per le organizzazioni più grandi, vuoi che un ticket Linear su un link marketing vada al team Marketing, e un ticket su un link docs vada al team Documentation. Il routing per tag gestisce questo.

Le regole di routing vivono in integration_configs.routing_json e vengono valutate dall'alto verso il basso. Una regola ha questo aspetto:

[
  {
    "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 prima regola il cui glob corrisponde ad almeno un tag sul link vince. Se nulla corrisponde, la regola predefinita prende l'evento. La sintassi glob è la stessa dei filtri delle viste salvate di Linear, che i PM conoscono già.

Puoi anche instradare per failure_type. Alcuni team vogliono che tutti i fallimenti TLS vadano al team di piattaforma poiché di solito indicano una configurazione errata del certificato su un dominio personalizzato di un tenant. Aggiungi una regola con failure_type: tls_expired e hai finito.

Trigger personalizzati tramite webhook

Non tutti i team vogliono creare ticket Linear per ogni tipo di evento che pubblichiamo. Il catalogo completo degli eventi è documentato nella pagina della funzionalità webhooks, ma le combinazioni più comuni che i team configurano insieme a Linear sono:

• link.created a un team Linear per audit di nuovi link (raro, solitamente per team di compliance)
• domain.takeover_detected per sorprese TLS su domini personalizzati
• link.scan_complete per ticket di riepilogo settimanale (un issue per ogni esecuzione di scansione, con tutti i link segnalati)

Se l'evento che vuoi non è nel catalogo, puoi costruirne uno personalizzato usando il target webhook generico e la nostra guida all'osservabilità. Oppure invia semplicemente una richiesta di funzionalità sulla nostra board Linear pubblica - meta ma ricorsivo.

Prezzi e cosa ottieni con ciascun piano

L'integrazione Linear è inclusa nel tier Pro e superiori. Con Free, puoi connettere Linear ma ottieni solo broken_link_hook (senza soglia clic o trigger personalizzati). Consulta la pagina dei prezzi per la matrice completa. Se sei un team più grande che sta valutando questa integrazione per motivi di compliance - ad esempio, l'articolo 32 del GDPR richiede di rilevare le perdite di dati dai reindirizzamenti rotti che puntano a domini squattati - la pagina delle soluzioni Enterprise descrive cosa offriamo su larga scala.

Letture correlate

• Webhook per eventi link: guida per sviluppatori - l'event bus sottostante che alimenta tutte le integrazioni, inclusa Linear.
• Collegare Sentry a 12 servizi Go - come monitoriamo il dispatcher che attiva gli eventi Linear, in modo da sapere quando il dispatcher stesso è in difficoltà.
• Strategia di prevenzione del link rotting - la storia operativa più ampia alla base del motivo per cui abbiamo costruito il rilevamento di link rotti.

Il catalogo completo delle integrazioni elenca 43 vendor a giugno 2026, con Linear tra i 20 attivi. Se il tuo team usa Jira invece, quell'adapter è in beta - scrivici e ti attiviamo.