Webhooks

Webhooks permitem que você receba notificações em tempo real quando seus links são clicados. Quando um clique ocorre, o Linkly envia uma solicitação POST para a(s) URL(s) especificada(s) com informações detalhadas sobre o clique.

Casos de Uso

• Plataformas de Automação: Acione fluxos de trabalho em Make ou Zapier quando links são clicados
• Análise Personalizada: Envie dados de cliques para seu próprio sistema de análise
• Atualizações de CRM: Atualize registros de clientes quando eles clicarem em links
• Notificações no Slack: Receba notificações no Slack quando links importantes são clicados
• Rastreamento de Leads: Acompanhe quando prospects interagem com seus links

Dica: Para a maioria dos casos de uso de automação, nossa integração com Make ou integração com Zapier são mais fáceis de configurar do que webhooks personalizados. Elas incluem acionadores de clique instantâneos alimentados por webhooks, sem exigir codificação.

Nota: Se você configurar webhooks em ambos os níveis, ambos serão acionados para cliques nesse link.

Payload do Webhook

Quando um clique ocorre, o Linkly envia uma solicitação POST com o seguinte 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"
    }
  }
}

Campos do Payload

Informações do Evento

Objeto Link

Objeto Click

Nota de Privacidade: Endereços IP nunca são incluídos nos payloads dos webhooks.

Integrações com Plataformas de Automação

Para uma configuração mais fácil sem codificação personalizada, use nossas integrações nativas:

• Integração com Make - Plataforma de automação visual com acionadores de clique instantâneos
• Integração com Zapier - Conecte o Linkly a milhares de aplicativos sem código

Ambas as integrações usam webhooks internamente, mas lidam com toda a configuração automaticamente.

Melhores Práticas

Múltiplos Webhooks

Você pode adicionar várias URLs de webhook (uma por linha). Todas as URLs receberão o mesmo payload quando um clique ocorrer.

Tratamento de Erros

• Webhooks são fire-and-forget - o Linkly não tenta novamente entregas com falha
• Falhas de webhook nunca afetam o redirecionamento - usuários sempre atingem seu destino
• Certifique-se de que seu endpoint de webhook responde rapidamente (< 5 segundos recomendado)

Segurança

• Use endpoints HTTPS para URLs de webhook
• Valide solicitações recebidas no seu manipulador de webhook
• Considere adicionar um parâmetro secreto à sua URL de webhook para verificação

Testes

1. 1
   Configure uma URL de webhook usando um serviço como webhook.site ou RequestBin
2. 2
   Clique no seu link
3. 3
   Inspecione o payload recebido
4. 4
   Uma vez verificado, mude para sua URL de webhook de produção

Acesso à API

Você também pode gerenciar webhooks programaticamente via 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

Veja a Documentação da API para detalhes.