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 specificato con informazioni dettagliate su ogni evento.

Casi di utilizzo

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

Suggerimento: Per la maggior parte dei casi di utilizzo dell'automazione, la nostra integrazione Make o integrazione Zapier sono più facili da configurare rispetto ai webhook personalizzati. Includono trigger di clic istantanei basati sui 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 eventi per quel link, un webhook a livello di workspace riceve eventi per ogni link nel workspace. Controlla il campo event di primo livello per distinguerli:

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

Oggetto Link

Oggetto Click

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'è un oggetto click — ottieni l'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,
    "rules": []
  }
}

Integrazioni con piattaforme di automazione

Per una configurazione più facile senza codifica personalizzata, 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 sotto il cofano ma gestiscono tutta la configurazione automaticamente.

Migliori pratiche

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 non riuscite
• Gli errori dei webhook non influiscono mai sul 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 gestore webhook
• Considera l'aggiunta di un parametro segreto all'URL webhook per la verifica

Testing

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

Consulta la Documentazione API per i dettagli.