Introdução

Se você já configurou uma integração entre dois serviços — por exemplo, para que os dados de um sistema cheguem automaticamente a um CRM ou a uma planilha do Google Sheets —, provavelmente já se deparou com o termo "webhook". É uma daquelas tecnologias que sustentam silenciosamente boa parte da automação moderna, desde notificações no Slack até a sincronização de pedidos em uma loja virtual. Neste artigo, vamos explicar o que são webhooks em termos simples, em que se diferenciam das requisições comuns a uma API, e como configurar, na prática, notificações de cliques para links curtos usando os webhooks do Lix.li.

O que é um webhook, em termos simples

Um webhook é uma forma de transmitir dados automaticamente de um serviço para outro no momento em que um determinado evento acontece. Em vez de o seu sistema perguntar constantemente "surgiu algo novo?", o próprio serviço envia os dados para o seu servidor assim que o evento ocorre. A forma mais simples de entender a diferença é com uma analogia do correio:

Uma requisição comum a uma API é como ir você mesmo até a caixa de correio repetidamente para conferir se chegou uma carta.
Um webhook é como assinar um serviço de entrega: a carta chega sozinha à sua porta assim que está pronta. Tecnicamente, um webhook é apenas uma requisição HTTP comum (geralmente POST) que um servidor envia para uma URL previamente configurada em outro servidor sempre que o evento correspondente acontece — o pagamento de um pedido, a mudança de status de uma tarefa ou, no caso do Lix.li, um clique em um link curto.

Para que servem os webhooks

Os webhooks resolvem um problema bem específico: como obter dados atualizados sem precisar consultar constantemente ("polling") um serviço externo. Sem webhooks, para saber sobre novos eventos você teria que enviar requisições periódicas a uma API — a cada minuto, a cada cinco minutos — e verificar toda vez se há algo novo. Isso gera uma carga desnecessária em ambos os servidores e sempre acrescenta um atraso entre o momento em que o evento ocorre e o momento em que você fica sabendo dele. Os webhooks invertem essa lógica: o serviço avisa você quando algo acontece. Isso é especialmente útil para:

Automatizar processos de negócio — por exemplo, registrar automaticamente novos leads em um CRM.
Integrações com análise de dados — enviar dados de cliques para o seu próprio sistema de monitoramento.
Bots e notificações — enviar eventos para um bot do Telegram ou para um canal do Slack da equipe.
Sincronização de dados — atualizar planilhas do Google Sheets, painéis ou sistemas internos em tempo real.

Como funcionam os webhooks: o exemplo do Lix.li

No Lix.li, os webhooks permitem que você receba informações sobre os cliques nos seus links curtos diretamente no seu próprio servidor — de forma automática, sem precisar consultar constantemente a API do serviço. Isso é útil se você quiser enviar esses eventos para o seu CRM, um sistema de análise de dados, o Google Sheets, um bot do Telegram ou qualquer outro sistema de automação.

Como funciona por dentro

Os cliques não são enviados um a um: eles são acumulados e entregues em lotes, a cada poucos minutos. Isso reduz a carga tanto no seu servidor quanto no do Lix.li.
A entrega acontece quase em tempo real, mas não instantaneamente — os webhooks são projetados para cenários em que um atraso de alguns minutos é aceitável, não para uma reação instantânea a cada clique individual.
A entrega é garantida sob o princípio de "pelo menos uma vez": se ocorrer uma falha de rede durante o envio, um lote pode chegar duplicado. Por isso, cada evento tem um event_id único, que você deve usar para filtrar duplicatas no seu lado.

Configurando um webhook no painel de controle

O recurso de webhooks está disponível no plano Premium. A configuração leva apenas alguns passos:

Abra a seção "Webhooks" no seu painel de controle e clique em "Adicionar."
Informe:
- a URL receptora — o endereço no seu servidor que vai aceitar as requisições recebidas (por exemplo, https://api.seusite.com/webhooks/lix);
- o escopo — se deve enviar eventos de todos os links, de um grupo específico de links, ou apenas de um único link;
- se deve incluir o endereço IP do visitante nos dados do evento (desativado por padrão, já que se trata de dados pessoais).
Logo após criar o webhook, você verá uma chave secreta, exibida apenas uma vez — certifique-se de salvá-la, pois ela é usada para verificar a autenticidade das requisições recebidas.
Clique em "Testar" — o serviço enviará um evento de teste e mostrará se o seu servidor respondeu corretamente.

O que chega ao seu servidor

Cada requisição é enviada usando o método POST com um corpo no formato application/json. Além dos próprios dados, a requisição inclui alguns cabeçalhos de serviço:

Cabeçalho	Finalidade
`X-Lix-Signature`	A assinatura do corpo da requisição, no formato `sha256=` — usada para verificação de autenticidade.
`X-Lix-Timestamp`	O momento em que a requisição foi enviada, como um timestamp Unix.
`X-Lix-Delivery`	Um identificador único da entrega.
`User-Agent`	Definido como `Lix-Webhooks/1.0`.
O corpo da requisição contém o próprio lote de eventos:

{
  "delivery_id": "0f3b9c2e-6a1d-4e88-9d5a-2f8c1b7a4e10",
  "event_type": "redirects.batch",
  "sent_at": "2026-06-01T12:05:00Z",
  "window": {
    "from": "2026-06-01T12:00:00Z",
    "to":   "2026-06-01T12:03:30Z"
  },
  "count": 2,
  "truncated": false,
  "events": [
    {
      "event_id":   "2ef7bde608ce5404e97d5f042f95f89f1c232871",
      "link_id":    12345,
      "datetime":   "2026-06-01T12:01:00Z",
      "country":    "US",
      "city":       "Boston",
      "browser":    "Chrome",
      "os":         "Windows",
      "device":     "Desktop",
      "ref_domain": "google.com",
      "group_id":   null,
      "is_bot":     false
    }
  ]
}

Cada evento dentro do lote inclui o ID do link, o horário do clique em UTC, país, cidade, navegador, sistema operacional, tipo de dispositivo, o domínio de onde o clique veio, o ID do grupo (se definido) e um indicador de se foi um bot. O endereço IP do visitante só é incluído se você tiver ativado explicitamente essa opção ao configurar o webhook. Se um número muito grande de eventos tiver se acumulado, um lote pode ser marcado com truncated: true — isso significa que parte dos dados chegará na próxima entrega, e nada é perdido.

Como verificar a autenticidade de uma requisição

Como a URL do seu servidor pode, tecnicamente, receber uma requisição de qualquer lugar, é importante confirmar que uma requisição realmente veio do Lix.li e não é falsificada. É para isso que serve a assinatura no cabeçalho X-Lix-Signature. O princípio de verificação é o seguinte: você pega o corpo "bruto" (não processado) da requisição, calcula um hash HMAC-SHA256 usando sua chave secreta, e compara o resultado com o que veio no cabeçalho. A comparação deve ser feita de forma segura (tempo constante) para evitar ataques de temporização. Exemplo em PHP:

$raw    = file_get_contents('php://input');
$secret = 'seu_secret';
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_LIX_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Exemplo em Node.js (Express):

const crypto = require('crypto');
// é importante obter o corpo BRUTO: app.use(express.raw({ type: 'application/json' }))
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.body).digest('hex');
const got = req.header('X-Lix-Signature') || '';
if (expected.length !== got.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got))) {
  return res.sendStatus(401);
}

Exemplo em Python (Flask):

import hmac, hashlib
raw = request.get_data()  # bytes brutos
expected = 'sha256=' + hmac.new(secret.encode(), raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get('X-Lix-Signature', '')):
    return '', 401

Requisitos para o seu servidor receptor

Para que os webhooks funcionem de forma estável, seu servidor precisa seguir algumas regras:

Responder com um código 2xx. Qualquer outro código, ou um tempo limite excedido, é considerado uma falha, e a entrega será repetida.
Responder rápido. Você tem apenas alguns segundos para responder — evite processar os dados de forma síncrona dentro do próprio manipulador da requisição. A abordagem correta é: salvar rapidamente os dados recebidos (em uma fila ou banco de dados, por exemplo), retornar 2xx, e processá-los separadamente depois.
Deduplicar pelo event_id. Devido ao mecanismo de nova tentativa, o mesmo evento pode ocasionalmente chegar duas vezes.
Ser idempotente. Reprocessar o mesmo lote não deve corromper seus dados.
Sempre verificar a assinatura em cada requisição recebida.
Usar HTTPS. Endereços locais e internos não são aceitos para receber webhooks.

O que acontece em caso de falhas

Se o seu servidor não responder com um código 2xx, o Lix.li tenta novamente a entrega com um intervalo cada vez maior entre as tentativas. Se o receptor não responder de forma alguma por um período prolongado (muitas tentativas falhas seguidas), o webhook é pausado automaticamente para evitar enviar dados para o vazio. Isso é exibido no registro de entregas do seu painel de controle, e assim que você corrigir o problema no seu lado, pode reativar o webhook.

Gerenciando webhooks no painel de controle

Para cada webhook configurado, as seguintes ações estão disponíveis:

Testar — enviar um único evento de teste e ver imediatamente o resultado: sucesso, ou o código de resposta específico do seu servidor.
Pausar / Retomar — interromper ou retomar temporariamente a entrega de eventos.
Trocar a chave secreta — gerar uma nova chave para substituir a anterior; a chave antiga deixa de funcionar instantaneamente, então não se esqueça de atualizá-la também no seu lado assim que possível.
Excluir — remover o webhook completamente.
Registro de entregas — um histórico das entregas recentes, mostrando status, código de resposta HTTP, número de eventos no lote e horário de envio.

Perguntas frequentes

Com que rapidez os eventos chegam? Em lotes, aproximadamente a cada poucos minutos, com um pequeno atraso de processamento. Não é uma entrega push instantânea, mas sim um cenário quase em tempo real. O mesmo evento pode chegar duas vezes? Sim, se uma entrega for reenviada após uma falha de rede. É exatamente por isso que é importante deduplicar os eventos pelo campo event_id no seu lado. A ordem dos eventos é garantida? Dentro de um mesmo lote, os eventos seguem uma ordem cronológica, mas não há garantia rígida de ordem entre lotes diferentes — use o campo datetime de cada evento para ordená-los. O que acontece com volumes de tráfego muito altos? Se muitos eventos se acumularem em um mesmo intervalo, o lote é marcado com truncated: true, e o restante dos dados chega na próxima entrega — nenhum dado é perdido nesse processo. O HTTPS é obrigatório? Sim, o endereço do receptor deve começar com https://. Endereços locais e internos não são aceitos. Posso receber eventos apenas de um link ou de um grupo de links? Sim, ao criar um webhook você pode escolher o escopo "Um link" ou "Grupo" em vez de todos os links da conta.

Exemplo completo de um manipulador em PHP

Abaixo está um exemplo mínimo, porém funcional, de um manipulador que verifica a assinatura, responde rapidamente e processa os eventos com proteção contra duplicatas: