Webhook

I webhook ti consentono 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 specificato 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 sui link
• Notifiche Slack: Ricevi notifiche su Slack quando i link importanti vengono cliccati
• Tracciamento dei lead: Traccia quando i prospect interagiscono con i tuoi link

Suggerimento: Per la maggior parte dei casi di automazione, l'integrazione Make o l'integrazione Zapier sono più facili da configurare rispetto ai webhook personalizzati. Includono trigger di clic istantanei alimentati da webhook, senza necessità di codifica.

Nota: Se configuri 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 riceve gli eventi per quel link, un webhook a livello di workspace riceve gli eventi per ogni link nel workspace. Controlla il campo event di livello superiore per distinguerli:

Payload del webhook

Payload del 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",
    "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": {
    "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

Informazioni sull'evento

Oggetto link

Oggetto clic

Nota sulla privacy: Gli indirizzi IP non sono 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 esiste un oggetto click — ottieni event, 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,
    "rules": []
  }
}

Integrazioni con piattaforme di automazione

Per una configurazione più semplice senza codifica personalizzata, utilizza le nostre integrazioni native:

• Integrazione Make - Piattaforma di automazione visiva con trigger di clic istantanei
• Integrazione Zapier - Connetti Linkly a migliaia di app senza codice

Entrambe le integrazioni utilizzano webhook dietro le quinte ma gestiscono automaticamente tutta la configurazione.

Best practice

Webhook multipli

Puoi aggiungere più URL di 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 tenta di reinviare i deliveries non riusciti
• I guasti dei webhook non influiscono mai sul reindirizzamento - gli utenti raggiungono sempre la loro destinazione
• Assicurati che il tuo endpoint webhook risponda rapidamente (< 5 secondi consigliato)

Sicurezza

• Utilizza endpoint HTTPS per gli URL dei webhook
• Convalida le richieste in arrivo nel tuo gestore di webhook
• Valuta l'aggiunta di un parametro segreto all'URL del webhook per la verifica

Test

1. 1
   Configura un URL di 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 del 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

Consulta la Documentazione API per i dettagli.