Webhooks: assine eventos de links e cliques

Os webhooks enviam eventos do Elido para o seu servidor assim que acontecem. Use-os em vez de fazer polling na API quando precisar de dados em tempo real — casos de uso típicos incluem sincronizar metadados de links com seu CRM, construir um dashboard personalizado ou iniciar um pipeline de CI quando um link é publicado.

Adicionar um endpoint de webhook#

Dashboard → Webhooks → New endpoint.
Cole a URL para a qual devemos fazer POST. Deve ser HTTPS — rejeitamos HTTP simples no momento da criação.
Escolha os tipos de eventos que você quer. A lista completa está abaixo.
(Opcional) Cole um signing secret ou deixe-nos gerar um. O secret é exibido uma vez; copie-o antes de sair da página.
Save. Enviamos um evento de teste imediatamente para que você possa confirmar que o endpoint está acessível.

Catálogo de eventos#

Os tipos de eventos atuais. Os nomes seguem o formato <resource>.<action> e permanecem estáveis entre versões.

link.created — um novo link curto foi criado.
link.updated — a URL de destino, slug, expiração ou senha foi alterada.
link.deleted — o link foi excluído de forma suave (ainda recuperável por 30 dias).
link.clicked.aggregated — a cada 60 segundos enviamos as contagens de cliques por link para a janela anterior. Não entregamos eventos de clique individuais via webhooks (o volume esmagaria a maioria dos endpoints) — use a exportação de cliques para dados de eventos brutos.
domain.verified — a verificação DNS de um domínio personalizado foi aprovada.
domain.tls_renewed — o Caddy renovou o certificado TLS para um domínio personalizado.
qr.generated — um SVG/PNG de QR code foi renderizado.
abuse.flagged — nosso scanner de URL marcou um destino como suspeito.
member.invited / member.removed — mudanças na composição do workspace.

Estrutura do payload#

Cada evento tem o mesmo envelope:

{
  "id": "evt_2c8L9N4M5",
  "type": "link.created",
  "created_at": "2026-05-15T09:42:11.382Z",
  "workspace_id": 4123,
  "data": {
    "link_id": 891234,
    "slug": "spring-2026",
    "destination": "https://acme.com/spring-sale",
    "created_by": "user_5821"
  }
}

id é único por entrega. Use-o para idempotência — se você receber o mesmo id duas vezes (porque fizemos uma nova tentativa), ignore o duplicado.

Verificação de assinaturas#

Assinamos cada corpo de webhook com HMAC-SHA256 usando o secret do seu endpoint. A assinatura está no cabeçalho Elido-Signature no formato t=<unix_ts>,v1=<hex>.

Para verificar em Node:

import { createHmac } from "node:crypto";

function verify(secret: string, body: string, header: string): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=")),
  );
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${body}`)
    .digest("hex");
  return expected === parts.v1;
}

Incluímos o timestamp no payload assinado para prevenir ataques de replay. Rejeite eventos onde |now - t| > 300 segundos.

Tentativas#

Fazemos novas tentativas em entregas com falha (qualquer resposta não-2xx, ou nenhuma resposta em 10 segundos) com backoff exponencial: 30s, 1m, 5m, 30m, 2h, 12h. Após 6 falhas marcamos o endpoint como failing e paramos de tentar novamente para esse evento específico. O endpoint permanece inscrito; novos eventos continuam tentando a entrega.

Se o endpoint permanecer failing por 5 entregas consecutivas → o desabilitamos automaticamente e enviamos um e-mail ao proprietário do workspace. Reative-o no dashboard depois de corrigir seu servidor.

Log de entregas#

Abra qualquer webhook no dashboard para ver as últimas 500 entregas, com código de status, tempo de resposta e o corpo de requisição/resposta para cada uma. Entregas com falha podem ser reproduzidas manualmente nesta visualização.

Testes locais#

Use o CLI do Elido para encaminhar webhooks para o localhost:

npx @elido/cli webhooks forward --url http://localhost:3000/webhooks

O CLI registra um endpoint temporário que dura até você pressionar Ctrl-C, faz o túnel das entregas para sua máquina e imprime o corpo da requisição para cada evento.

Limites#

20 endpoints por workspace (Pro), 100 (Business).
Tamanho máximo de payload assinado de 10 KB. Payloads maiores são divididos — data inclui um indicador truncated: true e uma URL para buscar o corpo completo.
50 eventos por segundo sustentados por endpoint. Picos são enfileirados.

Solução de problemas#

O endpoint reporta 401 no log de entregas. Seu endpoint está verificando assinaturas com o secret incorreto. Compare o secret em Webhooks → Endpoint → Settings com o que seu servidor tem armazenado.

Alguns eventos chegam duas vezes. Ou fizemos uma nova tentativa após uma resposta lenta, ou seu endpoint expirou sem responder. Use o id do evento para idempotência.

Os conteos de link.clicked.aggregated não coincidem com o dashboard de analytics. O dashboard é em tempo real (dentro de 30s do clique); o webhook tem uma janela de 60s. Há também uma pequena discrepância (~1%) porque bots filtrados do dashboard ainda são incluídos nos agregados brutos até que a janela do filtro de bots se feche.