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.

1
2
3

Puoi aggiungere più URL webhook. Tutti gli URL riceveranno lo stesso payload quando il link viene cliccato.

Inserisci i tuoi URL webhook, uno per riga.
Inserisci i tuoi URL webhook, uno per riga.
4

I webhook a livello di link si attivano solo quando quel link specifico viene cliccato.

Come configurare i webhook a livello di workspace

1

Vai a Impostazioni (icona dell'ingranaggio nella barra laterale).

2

Fai clic su Impostazioni workspace

3

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.

Inserisci i tuoi URL webhook, uno per riga.
Inserisci i tuoi URL webhook, uno per riga.
4

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:

eventInviato quando
clickUn link breve viene cliccato. Include un oggetto click con i dati della richiesta del visitatore.
link.createdUn nuovo link viene creato nel workspace.
link.updatedLe 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.deletedUn 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

CampoDescrizione
eventclick, link.created, link.updated, o link.deleted
timestampTimestamp ISO 8601 del clic
CampoDescrizione
idIdentificatore univoco del link
nameNickname del link
urlURL di destinazione originale
full_urlL'URL del link breve
domainDominio personalizzato (se configurato)
slugPercorso URL/slug
metadataI tuoi dati chiave-valore allegati al link, ad esempio ID dal tuo sistema. Sempre un oggetto, vuoto se non è impostato. Vedi metadati del link
destinationDestinazione effettiva per questo clic (potrebbe differire da url se le regole si applicano)
workspace_idIdentificatore del workspace
enabledSe il link è attivo
rulesArray di regole di reindirizzamento (geo, device, rotator)
utm_*Parametri UTM se configurati
og_*Impostazioni Open Graph se configurate

Oggetto click

CampoDescrizione
idIdentificatore 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
countryCodice paese a due lettere (ad es. "US", "GB")
is_eu_countrySe il clic proviene dall'UE
platformPiattaforma del dispositivo (desktop, ios, android, ecc.)
browser_nameNome del browser (Chrome, Safari, Firefox, ecc.)
refererURL di riferimento (se disponibile)
ispInternet Service Provider
bot_nameIdentificatore del bot (null per i clic umani)
destinationURL di destinazione finale per questo clic
paramsParametri di query passati al link

Nota sulla privacy: Gli indirizzi IP non vengono mai inclusi nei payload dei webhook.

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:

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

  1. 1
    Configura un URL webhook utilizzando un servizio come webhook.site o RequestBin
  2. 2
    Fai clic sul tuo link
  3. 3
    Ispeziona il payload ricevuto
  4. 4
    Una 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.

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

Confronta i piani →

Traccia 500 clic mensili gratuitamente.