Webhook
I webhook ti permettono di ricevere notifiche in tempo reale sui tuoi link — sia quando vengono cliccati che quando vengono creati, aggiornati o eliminati. Linkly invia una richiesta POST all'URL (o agli URL) specificati con informazioni dettagliate su ogni evento.
Casi d'uso
- Piattaforme di automazione: Attiva flussi di lavoro in Make o Zapier quando i link vengono cliccati
- Analitiche personalizzate: Invia i dati dei clic al tuo sistema di analitiche
- Aggiornamenti CRM: Aggiorna i record dei clienti quando cliccano i link
- Notifiche Slack: Ricevi notifiche in Slack quando i link importanti vengono cliccati
- Tracciamento dei lead: Traccia quando i prospect interagiscono con i tuoi link
Consiglio: Per la maggior parte dei casi d'uso di automazione, la nostra integrazione Make o integrazione Zapier sono più facili da configurare rispetto ai webhook personalizzati. Includono trigger di clic istantanei basati su webhook, senza necessità di coding.
Come configurare i webhook a livello di link
Vai a Link e fai clic sul link che desideri configurare.
Scorri verso il basso fino alla sezione Webhook.
Inserisci i tuoi URL webhook, uno per riga.
Puoi aggiungere più URL webhook. Tutti gli URL riceveranno lo stesso payload quando il link viene cliccato.

Fai clic su Salva.
I webhook a livello di link si attivano solo quando quel link specifico viene cliccato.
Come configurare i webhook a livello di workspace
Vai a Impostazioni (icona dell'ingranaggio nella barra laterale).
Fai clic su Impostazioni workspace
Inserisci i tuoi URL webhook, uno per riga.
Puoi aggiungere più URL webhook. Tutti gli URL riceveranno lo stesso payload quando viene cliccato qualsiasi link nel tuo workspace.

Fai clic su Salva impostazioni.
I webhook a livello di workspace si attivano per ogni clic su qualsiasi link nel tuo workspace.
Nota: Se configuri i webhook a entrambi i livelli, entrambi si attiveranno per i clic su quel link.
Eventi
Ogni webhook riceve tutti i tipi di evento per il suo ambito — un webhook a livello di link ottiene gli eventi per quel link, un webhook a livello di workspace ottiene gli eventi per ogni link nel workspace. Controlla il campo event di primo livello per distinguerli:
event | Inviato quando |
|---|---|
click | Un link breve viene cliccato. Include un oggetto click con i dati della richiesta del visitatore. |
link.created | Un nuovo link viene creato nel workspace. |
link.updated | Le impostazioni di un link cambiano. Si attiva su ogni aggiornamento, inclusi gli edit con salvataggio automatico, quindi potresti riceverne diversi per sessione di editing. |
link.deleted | Un link viene eliminato. L'oggetto link mantiene lo slug e il dominio che aveva prima dell'eliminazione. |
Payload del webhook
Payload di clic
Quando si verifica un clic, Linkly invia una richiesta POST con il seguente payload JSON:
{
"event": "click",
"timestamp": "2025-01-15T10:30:00Z",
"link": {
"id": 12345,
"name": "My Campaign Link",
"url": "https://example.com/landing-page",
"full_url": "https://yourdomain.com/abc123",
"domain": "yourdomain.com",
"slug": "/abc123",
"metadata": {
"order_id": "A-10293",
"crm_contact_id": "3f2b8c1e-9a47-4d0e-b6a5-1c2d3e4f5a6b"
},
"destination": "https://example.com/landing-page",
"workspace_id": 1,
"enabled": true,
"cloaking": false,
"forward_params": true,
"block_bots": true,
"public_analytics": false,
"utm_source": "newsletter",
"utm_medium": "email",
"utm_campaign": "spring-sale",
"og_title": "Special Offer",
"og_description": "Check out our spring sale!",
"rules": [
{
"what": "country",
"matches": "US",
"url": "https://example.com/us-landing"
}
]
},
"click": {
"id": "01KYPGEEPJSPR3S564QRBDGA1W",
"country": "US",
"is_eu_country": false,
"platform": "desktop",
"browser_name": "Chrome",
"referer": "https://twitter.com/",
"isp": "Comcast",
"bot_name": null,
"destination": "https://example.com/landing-page",
"params": {
"utm_source": "twitter"
}
}
}
Campi del payload
Info dell'evento
| Campo | Descrizione |
|---|---|
event | click, link.created, link.updated, o link.deleted |
timestamp | Timestamp ISO 8601 del clic |
Oggetto link
| Campo | Descrizione |
|---|---|
id | Identificatore univoco del link |
name | Nickname del link |
url | URL di destinazione originale |
full_url | L'URL del link breve |
domain | Dominio personalizzato (se configurato) |
slug | Percorso URL/slug |
metadata | I tuoi dati chiave-valore allegati al link, ad esempio ID dal tuo sistema. Sempre un oggetto, vuoto se non è impostato. Vedi metadati del link |
destination | Destinazione effettiva per questo clic (potrebbe differire da url se le regole si applicano) |
workspace_id | Identificatore del workspace |
enabled | Se il link è attivo |
rules | Array di regole di reindirizzamento (geo, device, rotator) |
utm_* | Parametri UTM se configurati |
og_* | Impostazioni Open Graph se configurate |
Oggetto click
| Campo | Descrizione |
|---|---|
id | Identificatore univoco per questo clic, un ULID di 26 caratteri. I caratteri iniziali codificano il tempo del clic, quindi gli ID vengono ordinati cronologicamente come stringhe semplici |
country | Codice paese a due lettere (ad es. "US", "GB") |
is_eu_country | Se il clic proviene dall'UE |
platform | Piattaforma del dispositivo (desktop, ios, android, ecc.) |
browser_name | Nome del browser (Chrome, Safari, Firefox, ecc.) |
referer | URL di riferimento (se disponibile) |
isp | Internet Service Provider |
bot_name | Identificatore del bot (null per i clic umani) |
destination | URL di destinazione finale per questo clic |
params | Parametri di query passati al link |
Nota sulla privacy: Gli indirizzi IP non vengono mai inclusi nei payload dei webhook.
Payload del ciclo di vita del link
Gli eventi link.created, link.updated e link.deleted condividono una forma. Non c'è un oggetto click — ottieni event, un timestamp, e il link completo:
{
"event": "link.created",
"timestamp": "2026-06-20T10:30:00Z",
"link": {
"id": 12345,
"name": "My Campaign Link",
"url": "https://example.com/landing-page",
"full_url": "https://yourdomain.com/abc123",
"domain": "yourdomain.com",
"slug": "/abc123",
"workspace_id": 1,
"enabled": true,
"metadata": {
"order_id": "A-10293"
},
"rules": []
}
}
Integrazioni con piattaforme di automazione
Per una configurazione più semplice senza coding personalizzato, utilizza le nostre integrazioni native:
- Integrazione Make - Piattaforma di automazione visuale con trigger di clic istantanei
- Integrazione Zapier - Connetti Linkly a migliaia di app senza codice
Entrambe le integrazioni utilizzano i webhook under the hood ma gestiscono automaticamente tutta la configurazione.
Best practice
Webhook multipli
Puoi aggiungere più URL webhook (uno per riga). Tutti gli URL riceveranno lo stesso payload quando si verifica un clic.
Gestione degli errori
- I webhook sono fire-and-forget - Linkly non riprova le consegne fallite
- I fallimenti dei webhook non influenzano mai il reindirizzamento - gli utenti raggiungono sempre la loro destinazione
- Assicurati che il tuo endpoint webhook risponda rapidamente (< 5 secondi consigliati)
Sicurezza
- Utilizza endpoint HTTPS per gli URL webhook
- Convalida le richieste in arrivo nel tuo handler webhook
- Considera l'aggiunta di un parametro segreto all'URL del webhook per la verifica
Test
- 1Configura un URL webhook utilizzando un servizio come webhook.site o RequestBin
- 2Fai clic sul tuo link
- 3Ispeziona il payload ricevuto
- 4Una volta verificato, passa all'URL webhook di produzione
Accesso API
Puoi anche gestire i webhook a livello di programmazione tramite l'API:
POST /api/v1/link/:link_id/webhooks
DELETE /api/v1/link/:link_id/webhooks/:hook_id
GET /api/v1/link/:link_id/webhooks
POST /api/v1/workspace/:workspace_id/webhooks
DELETE /api/v1/workspace/:workspace_id/webhooks/:hook_id
GET /api/v1/workspace/:workspace_id/webhooks
Vedi la Documentazione API per i dettagli.
Webhook - Domande frequenti
Quali eventi possono inviare i webhook?
I webhook si attivano su quattro eventi, identificati dal campo event nel payload. Ricevi click quando un link viene cliccato, più link.created, link.updated e link.deleted quando i link cambiano. Ogni webhook riceve tutti i tipi di evento per il suo ambito, quindi esegui il branching sul campo event per gestire ciascuno.
Perché i miei webhook non si attivano?
Verifica che l'URL del webhook sia valido e accessibile, e che i webhook siano salvati sul link o sul workspace. Per gli eventi di clic, tieni presente che i webhook si attivano solo quando un clic viene effettivamente registrato - gli IP esclusi o i crawler saltati non li attiveranno.
Perché alcuni campi sono null nel payload del webhook?
Alcuni campi potrebbero essere null se le informazioni non erano disponibili (ad es. nessun referer), le impostazioni di privacy hanno impedito la raccolta, o il clic proveniva da un bot (in questo caso bot_name sarà popolato).
Linkly ritenta le consegne webhook fallite?
No. I webhook sono fire-and-forget. Le consegne fallite non vengono ritentate e Linkly non traccia lo stato di consegna del webhook. Le richieste webhook scadono dopo 5 secondi.
Linkly supporta i postback per il tracciamento delle conversioni?
No. I webhook di Linkly sono solo in uscita e si attivano quando si verificano i clic. Non possiamo ricevere dati di postback dalle reti di affiliazione o dalle piattaforme pubblicitarie. Per il tracciamento delle conversioni, utilizza il tracciamento nativo della piattaforma di destinazione, passa un ID clic tramite l'inoltro dei parametri di query, o utilizza la nostra integrazione BigQuery per unire i dati dei clic ai tuoi dati di conversione.
Dovrei usare i webhook o Make/Zapier?
Per la maggior parte dei casi d'uso di automazione, le nostre integrazioni Make o Zapier sono più facili da configurare. Utilizzano i webhook under the hood ma gestiscono automaticamente tutta la configurazione. Usa i webhook personalizzati quando hai bisogno di inviare dati ai tuoi sistemi o richiedi più controllo sull'integrazione.
Posso avere webhook sia su un link che sul workspace?
Sì. Se configuri i webhook a entrambi i livelli, entrambi si attiveranno quando quel link viene cliccato. Questo è utile se desideri la registrazione a livello di workspace più azioni specifiche per determinati link.
Chi può configurare i webhook?
I webhook su un singolo link hanno bisogno del ruolo Scrittura o superiore. I webhook workspace hanno bisogno del ruolo Amministratore o Proprietario. Vedi ruoli utente e permessi.
Disponibilità del piano
Disponibile da Business
Traccia 500 clic mensili gratuitamente.