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 requisiçã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 Customizada: Envie dados de cliques para seu próprio sistema de análise
  • Atualizações de CRM: Atualize registros de clientes quando eles clicam em links
  • Notificações do Slack: Receba notificações no Slack quando links importantes são clicados
  • Rastreamento de Leads: Rastreie 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 que webhooks personalizados. Elas incluem gatilhos de cliques instantâneos alimentados por webhooks, sem necessidade de codificação.

1
2
3

Você pode adicionar várias URLs de webhook. Todas as URLs receberão o mesmo payload quando o link é clicado.

Insira sua(s) URL(s) de webhook, uma por linha.
Insira sua(s) URL(s) de webhook, uma por linha.
4

Webhooks em nível de link acionam apenas quando esse link específico é clicado.

Como configurar webhooks em nível de workspace

1

Vá para Settings (ícone de engrenagem na barra lateral).

2

Clique em Workspace Settings

3

Insira sua(s) URL(s) de webhook, uma por linha.

Você pode adicionar várias URLs de webhook. Todas as URLs receberão o mesmo payload quando qualquer link no seu workspace é clicado.

Insira sua(s) URL(s) de webhook, uma por linha.
Insira sua(s) URL(s) de webhook, uma por linha.
4

Clique em Save Settings.

Webhooks em nível de workspace acionam para cada clique em qualquer link no seu workspace.

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

Eventos

Todo 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 workspace obtém eventos para cada link no workspace. Verifique o campo event de nível superior para diferenciá-los:

eventEnviado quando
clickUm link curto é clicado. Inclui um objeto click com os dados da requisição do visitante.
link.createdUm novo link é criado no workspace.
link.updatedAs configurações de um link mudam. É acionado a cada atualização, incluindo edições com salvamento automático, portanto você pode receber vários por sessão de edição.
link.deletedUm link é excluído. O objeto link mantém o slug e domínio que tinha antes da exclusão.

Payload do webhook

Payload de clique

Quando um clique ocorre, o Linkly envia uma requisiçã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",
    "metadata": {
      "order_id": "A-10293",
      "crm_contact_id": "3f2b8c1e-9a47-4d0e-b6a5-1c2d3e4f5a6b"
    },
    "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

CampoDescrição
eventclick, link.created, link.updated, ou link.deleted
timestampTimestamp ISO 8601 do clique
CampoDescrição
idIdentificador único do link
nameApelido do link
urlURL de destino original
full_urlA URL do link curto
domainDomínio personalizado (se configurado)
slugCaminho/slug da URL
metadataSeus próprios dados de chave-valor anexados ao link, por exemplo IDs do seu próprio sistema. Sempre um objeto, vazio se nenhum estiver definido. Veja link metadata
destinationDestino real para este clique (pode diferir de url se as regras forem aplicadas)
workspace_idIdentificador do workspace
enabledSe o link está ativo
rulesArray de regras de redirecionamento (geo, device, rotator)
utm_*Parâmetros UTM se configurados
og_*Configurações do Open Graph se configuradas

Objeto do clique

CampoDescrição
idIdentificador único para este clique, um ULID de 26 caracteres. Os caracteres iniciais codificam o tempo do clique, portanto os ids são classificados cronologicamente como strings simples
countryCódigo de país de duas letras (por exemplo, "US", "GB")
is_eu_countrySe o clique originou-se da UE
platformPlataforma do dispositivo (desktop, ios, android, etc.)
browser_nameNome do navegador (Chrome, Safari, Firefox, etc.)
refererURL referenciadora (se disponível)
ispProvedor de Serviços de Internet
bot_nameIdentificador de bot (null para cliques humanos)
destinationURL de destino final para este clique
paramsParâmetros de consulta passados para o link

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

Os eventos link.created, link.updated e link.deleted compartilham uma única forma. Não há um 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,
    "metadata": {
      "order_id": "A-10293"
    },
    "rules": []
  }
}

Integrações de plataformas de automação

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

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 várias URLs de webhook (uma por linha). Todas as URLs receberão o mesmo payload quando um clique ocorre.

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 chegam ao 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 requisiçõ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.

FAQs sobre Webhooks

Quais eventos os webhooks podem enviar?

Os webhooks acionam em quatro eventos, identificados pelo campo event no payload. Você obtém click quando um link é clicado, mais link.created, link.updated e link.deleted quando links mudam. Todo webhook recebe todos os tipos de eventos para seu escopo, portanto ramifique no campo event para lidar com cada um.

Por que meus webhooks não estão acionando?

Verifique se sua URL de webhook é válida e acessível, e se os webhooks estão salvos no link ou workspace. Para eventos de clique, observe que os webhooks acionam apenas quando um clique é realmente registrado - IPs excluídos ou crawlers ignorados não os dispararão.

Por que alguns campos são null no payload do webhook?

Alguns campos podem ser null se a informação não estava disponível (por exemplo, sem referenciador), as configurações de privacidade impediram a coleta, ou o clique foi de um bot (neste caso bot_name será preenchido).

O Linkly tenta novamente entregas de webhook com falha?

Não. Webhooks são fire-and-forget. Entregas com falha não são repetidas, e o Linkly não rastreia o status de entrega do webhook. Requisições de webhook expiram após 5 segundos.

O Linkly suporta postbacks para rastreamento de conversão?

Não. Webhooks do Linkly são apenas de saída e disparam quando cliques ocorrem. Não podemos receber dados de postback de redes de afiliados ou plataformas de anúncios. Para rastreamento de conversão, use o rastreamento nativo da plataforma de destino, passe um ID de clique via encaminhamento de parâmetro de consulta, ou use nossa integração com BigQuery para unir dados de cliques com seus dados de conversão.

Devo usar webhooks ou Make/Zapier?

Para a maioria dos casos de uso de automação, nossas integrações Make ou Zapier são mais fáceis de configurar. Elas usam webhooks sob o capô, mas lidam com toda a configuração automaticamente. Use webhooks personalizados quando precisar enviar dados para seus próprios sistemas ou exigir mais controle sobre a integração.

Sim. Se você configurar webhooks em ambos os níveis, ambos serão acionados quando esse link é clicado. Isso é útil se você deseja logging em todo o workspace mais ações específicas para certos links.

Quem pode configurar webhooks?

Webhooks em um único link precisam da função Escrita ou superior. Webhooks do workspace precisam da função Administrador ou Proprietário. Consulte funções de usuário e permissões.

Disponibilidade do plano

Disponível a partir do Business

Comparar planos →

Rastreie 500 cliques mensais com todos os recursos incluídos.