Webhook

I webhook ti permettono di ricevere notifiche in tempo reale sui tuoi link — sia quando vengono cliccati sia quando vengono creati, aggiornati o eliminati. Linkly invia una richiesta POST al tuo URL specificato con informazioni dettagliate su ogni evento.

Casi d'uso

• Piattaforme di automazione: Attiva i flussi di lavoro in Make o Zapier quando i link vengono cliccati
• Analytics personalizzati: Invia i dati dei clic al tuo sistema di analytics
• Aggiornamenti CRM: Aggiorna i record dei clienti quando cliccano sui link
• Notifiche Slack: Ricevi notifiche in Slack quando i link importanti vengono cliccati
• Tracciamento dei lead: Traccia quando i potenziali clienti interagiscono con i tuoi link

Suggerimento: 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 codifica.

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 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 primo livello per distinguerli:

Payload webhook

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

Info 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 c'è oggetto click — otterrai 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, usa le nostre integrazioni native:

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

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

Buone pratiche

Più webhook

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 ritenta le consegne non riuscite
• 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

• Usa endpoint HTTPS per gli URL webhook
• Convalida le richieste in entrata nel tuo gestore webhook
• Considera di aggiungere un parametro segreto all'URL del tuo webhook per la verifica

Test

1. 1
   Configura un URL webhook usando 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 al tuo 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

Consulta la Documentazione API per i dettagli.