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 links são clicados
• Análises Personalizadas: Envie dados de cliques para seu próprio sistema de análises
• Atualizações de CRM: Atualize registros de clientes quando eles clicam em links
• Notificações no 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 com Make ou integração com Zapier são mais fáceis de configurar do que webhooks personalizados. Elas incluem gatilhos de cliques instantâneos alimentados por webhooks, sem necessidade de codificação.

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

Eventos

Cada webhook recebe todos os tipos de eventos para seu escopo — um webhook no nível do link obtém eventos para esse link, um webhook no nível do workspace obtém eventos para cada link no workspace. Verifique o campo event no 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 nos payloads dos webhooks.

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

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

Melhores 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 fire-and-forget - O Linkly não tenta novamente entregas falhadas
• 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 de entrada 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 em 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.