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. O 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: Dispare fluxos de trabalho em Make ou Zapier quando os 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 clicarem em links
• Notificações do Slack: Receba notificações no Slack quando links importantes são clicados
• Rastreamento de Leads: Rastreie quando prospects se envolvem 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. Eles incluem gatilhos de cliques instantâneos alimentados por webhooks, sem necessidade de codificação.

Observação: 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 eventos para seu escopo — um webhook em nível de link obtém eventos para esse link, um webhook em nível de espaço de trabalho obtém eventos para cada link no espaço de trabalho. Verifique o campo event de nível superior para diferenciá-los:

Payload do webhook

Payload de clique

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": {
    "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"
    }
  }
}

Campos do payload

Informações do evento

Objeto de link

Objeto de clique

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

Payload do ciclo de vida do link

Os eventos link.created, link.updated e link.deleted compartilham uma forma. 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 o Linkly a milhares de aplicativos sem código

Ambas as integrações usam webhooks nos bastidores, 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 - os usuários sempre chegam ao seu destino
• Certifique-se de que seu endpoint de webhook responda 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 no seu link
3. 3
   Inspecione o payload recebido
4. 4
   Depois de 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.