Webhooks

Webhooks permitem que você receba notificações em tempo real sobre seus links — tanto quando são clicados quanto quando são criados, atualizados ou excluídos. Linkly envia uma solicitação POST para sua(s) URL(s) especificada(s) com informações detalhadas sobre cada evento.

Casos de uso

• Plataformas de Automação: Acionam fluxos de trabalho em Make ou Zapier quando links são clicados
• Analytics Personalizado: Enviar dados de cliques para seu próprio sistema de análise
• Atualizações de CRM: Atualizar registros de clientes quando clicam em links
• Notificações no Slack: Receba notificações no Slack quando links importantes são clicados
• Rastreamento de Leads: Rastrear quando potenciais clientes interagem com seus links

Dica: Para a maioria dos casos de uso de automação, nossa integração Make ou integração Zapier são mais fáceis de configurar do que webhooks personalizados. Incluem gatilhos de clique instantâneos baseados em webhooks, sem necessidade de codificação.

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

Eventos

Cada webhook recebe todos os tipos de evento de seu escopo — um webhook em nível de link obtém eventos desse link, um webhook em nível de workspace obtém eventos de cada link no workspace. Verifique o campo event de nível superior para diferenciá-los:

Payload do webhook

Payload de clique

Quando um clique ocorre, 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 de evento

Objeto Link

Objeto Click

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

Payload do ciclo de vida do link

Os eventos link.created, link.updated e link.deleted compartilham um formato. Não há objeto click — você obtém o event, um timestamp e o 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": []
  }
}

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 Make - Plataforma de automação visual com gatilhos de clique instantâneos
• Integração Zapier - Conecte Linkly a milhares de aplicativos sem código

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

Boas práticas

Múltiplos webhooks

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

Tratamento de erros

• Webhooks são dispara e esquece - Linkly não tenta novamente entregas falhadas
• Falhas do webhook nunca afetam o redirecionamento - usuários sempre chegam ao seu destino
• Certifique-se de que seu endpoint webhook responde rapidamente (< 5 segundos recomendado)

Segurança

• Use endpoints HTTPS para URLs de webhook
• Valide solicitações recebidas em 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 em seu link
3. 3
   Inspecione o payload recebido
4. 4
   Após verificar, 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.