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.
Como configurar webhooks em nível de link
Vá para Links e clique no link que deseja configurar.
Role para baixo até a seção Webhooks.
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 o link é clicado.

Clique em Save.
Webhooks em nível de link acionam apenas quando esse link específico é clicado.
Como configurar webhooks em nível de workspace
Vá para Settings (ícone de engrenagem na barra lateral).
Clique em Workspace Settings
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.

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:
event | Enviado quando |
|---|---|
click | Um link curto é clicado. Inclui um objeto click com os dados da requisição do visitante. |
link.created | Um novo link é criado no workspace. |
link.updated | As 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.deleted | Um 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
| Campo | Descrição |
|---|---|
event | click, link.created, link.updated, ou link.deleted |
timestamp | Timestamp ISO 8601 do clique |
Objeto do link
| Campo | Descrição |
|---|---|
id | Identificador único do link |
name | Apelido do link |
url | URL de destino original |
full_url | A URL do link curto |
domain | Domínio personalizado (se configurado) |
slug | Caminho/slug da URL |
metadata | Seus 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 |
destination | Destino real para este clique (pode diferir de url se as regras forem aplicadas) |
workspace_id | Identificador do workspace |
enabled | Se o link está ativo |
rules | Array de regras de redirecionamento (geo, device, rotator) |
utm_* | Parâmetros UTM se configurados |
og_* | Configurações do Open Graph se configuradas |
Objeto do clique
| Campo | Descrição |
|---|---|
id | Identificador ú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 |
country | Código de país de duas letras (por exemplo, "US", "GB") |
is_eu_country | Se o clique originou-se da UE |
platform | Plataforma do dispositivo (desktop, ios, android, etc.) |
browser_name | Nome do navegador (Chrome, Safari, Firefox, etc.) |
referer | URL referenciadora (se disponível) |
isp | Provedor de Serviços de Internet |
bot_name | Identificador de bot (null para cliques humanos) |
destination | URL de destino final para este clique |
params | Parâmetros de consulta passados para o link |
Nota de Privacidade: Endereços IP nunca são incluídos nos payloads de webhook.
Payload do ciclo de vida do link
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:
- 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 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
- 1Configure uma URL de webhook usando um serviço como webhook.site ou RequestBin
- 2Clique no seu link
- 3Inspecione o payload recebido
- 4Uma 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.
Posso ter webhooks em um link e no workspace?
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
Rastreie 500 cliques mensais com todos os recursos incluídos.