Os webhooks do encurtador de URL do Elido enviam por POST um envelope JSON assinado ao seu endpoint HTTPS sempre que algo muda em um workspace: um link é criado, editado, excluído, expira ou atinge o limite de cliques, um membro é convidado, um domínio é verificado. Cada requisição traz um header X-Elido-Signature: v1=<hex>, que é um HMAC-SHA256 sobre {timestamp}.{raw_body}, e uma entrega que falha recebe três tentativas em cerca de vinte minutos.
Os cliques têm o seu próprio evento, click.created, com regras próprias: um payload com privacidade reduzida, um limite de taxa por endpoint e uma opção para incluir tráfego de bots. A última seção trata dele. Este post é a metade de saída da superfície da API; o quickstart da API e dos SDKs do encurtador de URL cobre a metade de entrada, e smart links explicados é o conteúdo principal de recursos de onde vêm os eventos de link.
Quais eventos de link disparam um webhook hoje
Todo evento abaixo chega a um endpoint de webhook que o assinou pelo nome. O formulário de novo endpoint do painel oferece caixas de seleção para os oito mais comuns; a API aceita qualquer nome da lista.
| Evento | Dispara quando | Caixa no painel |
|---|---|---|
link.created | Um link é criado, individualmente ou em uma importação em massa | sim |
link.updated | Mudam destino, configurações ou status, edições em massa, restaurações | sim |
link.deleted | Um link é excluído, individualmente ou em massa | sim |
link.expired | Um link passa da data de expiração | só API |
link.cap_reached | Um link atinge a contagem máxima de cliques | só API |
link.broken | A checagem de link quebrado vê o destino falhando | só API |
click.created | Um clique é contado (bots e scanners ignorados, a menos que habilitados) | sim, nunca pré-marcado |
workspace.created, workspace.updated | Um workspace é provisionado ou suas configurações mudam | sim |
member.invited, member.removed | Um membro é adicionado (diretamente, por SCIM ou por convite aceito) ou removido | sim |
member.role_changed | O papel de um membro muda | só API |
invitation.created, invitation.accepted | Um convite é enviado ou aceito | só API |
domain.verified, domain.ssl_failed | Um domínio personalizado passa nas checagens de DNS, ou continua falhando nelas após 24 horas | só API |
audit.event | Qualquer entrada do log de auditoria | sim |
Links criptografados acrescentam mais dois, link.encrypted_created e link.encryption_rotated. Se você prefere não manter a lista atualizada à mão, crie um endpoint siem: ele recebe todos os eventos do workspace, entradas de auditoria incluídas, sem nenhum filtro de assinatura. A única exceção é click.created, que só chega a endpoints event que o marcam.
Os eventos de cobrança passam pela mesma fila. O serviço de cobrança publica subscription.created, subscription.activated, subscription.paused, subscription.resumed, subscription.frozen, subscription.unfrozen, subscription.change_scheduled, subscription.change_canceled, usage.threshold_80, usage.threshold_100 e usage.overage_charged. Um endpoint siem também os recebe.
No roadmap, ainda não disponíveis: filtros por endpoint como "só links na pasta X". Até lá, filtre por data.slug ou data.link_id no seu handler.
Criando um endpoint de webhook pela API
Um endpoint pertence a um workspace. Você o cria com um POST em /v1/workspaces/{workspace_id}/webhooks:
curl -X POST "https://api.elido.app/v1/workspaces/$WORKSPACE_ID/webhooks" \
-H "Authorization: Bearer elido_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/elido",
"events": ["link.created", "link.updated", "link.deleted"],
"description": "CRM sync",
"kind": "event"
}'
A resposta é 201 com o endpoint e, para os tipos event e siem, um segredo de uso único:
{
"endpoint": {
"id": 7,
"workspace_id": 42,
"url": "https://hooks.example.com/elido",
"events": ["link.created", "link.updated", "link.deleted"],
"is_active": true,
"description": "CRM sync",
"kind": "event",
"config": {},
"created_at": "2026-09-21T09:12:44Z"
},
"secret": "whsec_9f2c..."
}
O Elido gera o segredo; você não envia um. Copie-o agora, porque nenhuma chamada posterior o devolve. kind aceita seis valores. event e siem são as entregas JSON assinadas de que este post trata. discord, telegram, slack e sentry remodelam os mesmos eventos em uma mensagem de chat ou em um evento do Sentry, autenticam pela URL ou por um token de bot criptografado e não levam headers HMAC.
Os planos importam na criação. Um endpoint event exige Pro, Business ou Enterprise, e um workspace Free recebe 402 Payment Required (o painel abre o diálogo de upgrade no lugar). Um endpoint siem exige Business ou Enterprise. Os canais de chat e Sentry não têm restrição de plano. Os endpoints que já existem continuam entregando se o workspace fizer downgrade depois.
Permissões: ler endpoints e o log de entregas exige workspace.view. Criar, editar, excluir, rotacionar um segredo ou reenviar uma entrega exige workspace.edit, ou seja, um admin ou owner. Uma chave de API funciona dentro do workspace para o qual foi emitida e nunca acima do papel escolhido quando foi criada, então uma chave de nível viewer recebe um 403 no POST acima. Referência completa: a documentação de webhooks.
O envelope do payload do webhook
Toda entrega assinada tem o mesmo envelope de quatro campos. data guarda o registro que mudou, então, para eventos de link, é a linha do link:
{
"type": "link.created",
"workspace_id": 42,
"data": {
"id": 91834,
"workspace_id": 42,
"domain_id": 3,
"slug": "spring-sale",
"destination_url": "https://shop.example.com/spring",
"title": "Spring sale landing",
"tags": ["newsletter"],
"status": "active",
"expires_at": null,
"max_clicks": null,
"redirect_status": 302,
"created_by_user_id": 17,
"created_at": "2026-09-21T09:14:02.184311Z"
},
"timestamp": "2026-09-21T09:14:02Z"
}
Esse exemplo está reduzido; o data real traz todas as colunas do link, incluindo regras de segmentação, pasta, campanha e campos de varredura. Não há ID de evento nem short_url no corpo, então monte a URL curta a partir do seu domínio e do slug, se precisar dela. Os eventos agendados enviam um objeto menor: link.expired tem link_id, slug e destination_url, e link.cap_reached acrescenta cap e clicks.
Uma correção que você deve conhecer, caso tenha registrado payloads em log antes da correção de redação: os campos secretos agora são removidos antes de um payload sair do Elido. O password_hash de um link protegido por senha e o token de um convite costumavam aparecer em data; não aparecem mais, nem nas novas entregas nem no log de entregas. Se você guardou payloads antigos, vale apagar esses dados.
Verificando o header X-Elido-Signature
Cada requisição assinada carrega estes headers:
X-Elido-Signature: v1=5d8f0c3e...
X-Webhook-Signature: v1=5d8f0c3e...
X-Webhook-Timestamp: 1790068442
X-Webhook-Event: link.created
X-Webhook-Delivery: 55120
User-Agent: Elido-Webhooks/1.0
Os dois headers de assinatura têm o mesmo valor, e X-Webhook-Signature é o alias de compatibilidade retroativa. O Elido calcula o HMAC-SHA256, como definido na RFC 2104, com a string whsec_... inteira como chave, sobre o timestamp, um ponto e os bytes brutos do corpo. O digest em hexadecimal recebe o prefixo v1=. Não há campo t= dentro do header; o timestamp fica em um header próprio.
Em Node, assine os bytes brutos, não um objeto reserializado. O Express precisa de express.raw({ type: "application/json" }) nesta rota por esse motivo:
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyElido(secret, headers, rawBody, toleranceSec = 300) {
const ts = headers["x-webhook-timestamp"] ?? "";
if (!/^\d+$/.test(ts)) return false;
if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;
const mac = createHmac("sha256", secret).update(`${ts}.`).update(rawBody);
const expected = Buffer.from("v1=" + mac.digest("hex"));
// During a rotation the old secret signs X-Elido-Signature-Previous.
return ["x-elido-signature", "x-elido-signature-previous"].some((name) => {
const got = Buffer.from(headers[name] ?? "");
return got.length === expected.length && timingSafeEqual(got, expected);
});
}
A checagem de tamanho importa: o timingSafeEqual do Node lança uma exceção com buffers de tamanhos diferentes em vez de retornar false. A versão em Python com o módulo hmac padrão:
import hashlib
import hmac
import time
def verify_elido(secret: str, headers, raw_body: bytes, tolerance: int = 300) -> bool:
ts = headers.get("X-Webhook-Timestamp", "")
if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance:
return False
digest = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256)
expected = "v1=" + digest.hexdigest()
for name in ("X-Elido-Signature", "X-Elido-Signature-Previous"):
got = headers.get(name)
if got and hmac.compare_digest(got, expected):
return True
return False
Se a verificação continuar falhando, o guia de verificação de assinaturas de webhook tem uma versão em Go, um nó Code do n8n e as causas usuais de uma divergência. A janela de cinco minutos é uma checagem sua, não nossa. O Elido carimba um timestamp novo em cada tentativa, novas tentativas incluídas, então uma nova tentativa legítima nunca parece vencida. Sem a janela, qualquer pessoa que tenha capturado uma requisição poderia reproduzi-la na semana seguinte e a assinatura ainda bateria.
A rotação é POST /v1/workspaces/{workspace_id}/webhooks/{id}/rotate-secret, ou o botão Rotate na página do endpoint. Você recebe o novo segredo uma única vez. Nos sete dias seguintes, cada entrega também carrega X-Elido-Signature-Previous, assinado com o segredo antigo, e é por isso que as duas funções acima o testam. Implante o novo segredo a qualquer momento dessa semana e nada falha.
A política de retry dos webhooks
O worker de entrega pega as entregas pendentes a cada poucos segundos, então uma mudança em um link costuma chegar até você em segundos. Qualquer resposta 2xx marca a entrega como concluída. Um status que não seja 2xx, um erro de rede ou nenhuma resposta em 10 segundos conta como uma tentativa que falhou.
Três tentativas por entrega, vinte minutos de ponta a ponta. É curto de propósito e, sinceramente, é mais curto do que eu escolheria para um receptor atrás de uma VPN instável. Uma queda de duas horas do seu lado não será coberta pelas tentativas automáticas. O que a cobre é o log de entregas: GET /v1/workspaces/{workspace_id}/webhooks/{id}/deliveries lista cada entrega com status, código HTTP, latência, número de tentativas e horário da próxima nova tentativa, e a página do endpoint mostra as mesmas linhas com um botão Retry. O Retry, ou POST .../deliveries/{delivery_id}/retry, rearma uma entrega falha ou entregue com um orçamento novo de três tentativas e retorna 202. Uma entrega ainda pendente recebe 409.
Algumas falhas pulam as novas tentativas. Um endpoint do Telegram sem chat_id, ou um DSN do Sentry malformado, é marcado como falha na hora, porque repetir a requisição não corrige configuração. Para tirar um endpoint do ar sem excluí-lo, envie PUT com "is_active": false; endpoints pausados não recebem novas entregas.
Se o seu handler faz trabalho pesado, retorne 200 primeiro e enfileire o job. O corte de dez segundos é onde um handler lento mas bem-sucedido vira uma duplicata, o que nos leva à deduplicação.
Está planejando um receptor para a sua equipe? A página do recurso de webhooks mostra o lado do painel de tudo isso.
Idempotência e ordenação dos webhooks
O Elido entrega pelo menos uma vez. A seção sobre retry mostrou uma forma de surgir uma duplicata: seu handler confirma o trabalho, depois perde a janela de dez segundos, e o Elido envia de novo. Um Retry manual reenvia de propósito.
Os dois casos mantêm o mesmo valor de X-Webhook-Delivery, porque ele é o ID de uma entrega a um endpoint, não de uma tentativa. Use-o como chave:
CREATE TABLE elido_webhook_seen (
delivery_id BIGINT PRIMARY KEY,
received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- in the handler, inside the same transaction as your work:
INSERT INTO elido_webhook_seen (delivery_id) VALUES ($1)
ON CONFLICT (delivery_id) DO NOTHING
RETURNING delivery_id;
-- no row back means you've already handled this delivery
Dois endpoints assinando o mesmo evento recebem dois IDs de entrega diferentes, então deduplique por endpoint. Em raras reinicializações do nosso lado, um evento pode ser enfileirado duas vezes como entregas separadas; se uma gravação dupla puder causar dano, adicione uma segunda proteção sobre type mais data.id mais data.updated_at.
Não há promessa de ordenação. As entregas saem começando pela de vencimento mais antigo, mas uma nova tentativa de um evento anterior pode chegar depois de um evento posterior. Compare data.updated_at com o que você já guardou antes de sobrescrever um link, e não confie no timestamp do envelope para ordenar: ele tem precisão de apenas um segundo.
O webhook click.created
click.created envia uma entrega assinada por clique contado. Ele não fica no caminho do redirecionamento: o redirecionamento publica o clique e segue em frente, como o post sobre ingestão de cliques fire-and-forget explica, e o evento é montado depois a partir do clique armazenado. Espere alguns segundos entre o clique e o POST, não milissegundos.
O objeto data tem este formato:
{
"type": "click.created",
"workspace_id": 42,
"timestamp": "2026-11-12T10:04:31Z",
"data": {
"id": "clk_3_99120",
"link_id": 9183,
"workspace_id": 42,
"slug": "spring",
"host": "go.acme.example",
"short_url": "https://go.acme.example/spring",
"timestamp": "2026-11-12T10:04:29Z",
"country": "DE",
"device": "mobile",
"browser": "Safari",
"referer_host": "news.ycombinator.com",
"ip": "203.0.113.0",
"is_bot": false,
"is_scanner": false
}
}
Algumas regras definem o que chega:
- Privacidade em primeiro lugar. O payload é montado depois das configurações de privacidade de análises do workspace. O IP é sempre apenas a rede truncada (/24 no IPv4, /48 no IPv6) e fica totalmente de fora no modo sem dados pessoais. O referrer é cortado até o host; caminhos e query strings nunca saem.
- Bots ficam desligados por padrão. Cliques marcados como
is_botouis_scanner(um scanner de segurança de e-mail pré-carregando o link) são ignorados, a menos que você marque "Incluir cliques de bots e scanners" no endpoint ou envieconfig.include_bot_clicks: truepela API. Crawlers conhecidos e bots de pré-visualização de link nunca contam como cliques, então nunca são enviados. - Um limite de taxa, não uma fila. Cada endpoint recebe no máximo 50 eventos de clique por segundo. O excedente é descartado, não atrasado, então um link viral não consegue soterrar o seu receptor, e isso também significa que o webhook não é um registro completo no pico. Reconcilie com a API de análises se cada clique importa.
- Deduplique por
data.id. A entrega é at-least-once, como em todos os outros eventos.data.idpermanece o mesmo se um clique for processado duas vezes, eX-Webhook-Deliverycobre as novas tentativas de uma mesma entrega. - Mesmas tentativas e mesma assinatura. Três tentativas (agora, +5 minutos, +15 minutos) e a checagem de
X-Elido-Signaturedescrita antes neste post.
Só endpoints event que marcam click.created o recebem. O formulário do painel o lista, mas nunca o pré-marca, e endpoints Discord, Telegram, Sentry e siem não o recebem. Zapier (um Catch Hook em Webhooks by Zapier), Make (um Custom webhook) e n8n (um nó Webhook) podem usá-lo como gatilho.
Duas outras rotas ainda fazem sentido para dados de clique. Os forwarders de eventos transformam cada clique em um evento server-side em uma ferramenta que você já usa: eventos de clique de link no Mixpanel, eventos de clique do Klaviyo nos perfis ou métricas de redirecionamento no Datadog para painéis de operações. E a API de análises, GET /v1/analytics/workspaces/{workspace_id}/clicks/recent mais a exportação clicks.csv, é o registro completo. Webhooks vs polling para rastreamento de cliques percorre qual deles se encaixa.
Leia o conteúdo principal: smart links explicados.
Relacionados no blog
- Webhooks vs polling para rastreamento de cliques - quando empurrar e quando puxar.
- Quickstart da API e dos SDKs do encurtador de URL - a superfície de entrada da API.
- Ingestão de cliques fire-and-forget - por que os cliques nunca esperam chamadas de saída.
- Eventos de clique de link no Mixpanel - dados de clique como eventos server-side.
- Métricas de redirecionamento de links no Datadog - a saúde dos redirecionamentos em um painel de operações.
- Verifique assinaturas de webhook - checagens HMAC em Node, Python, Go e n8n, além de depurar uma divergência.
Perguntas frequentes
O Elido envia um webhook para cada clique em um link?
Sim, pelo evento click.created: uma entrega assinada por clique contado, alguns segundos depois de ele acontecer. Cliques de bots e de scanners de segurança são ignorados, a menos que o endpoint os inclua, e cada endpoint tem um limite de 50 eventos de clique por segundo, com o excedente descartado em vez de enfileirado. Para um registro completo de um link viral, leia também a API de análises.
Como verifico a assinatura de um webhook do Elido?
Calcule o HMAC-SHA256 sobre o valor de X-Webhook-Timestamp, um ponto e o corpo bruto da requisição, usando como chave o seu segredo whsec_. Codifique em hexadecimal, acrescente o prefixo v1= e compare em tempo constante com o header X-Elido-Signature. Rejeite timestamps com mais de cinco minutos.
Quantas vezes o Elido tenta de novo um webhook que falhou?
Cada entrega recebe três tentativas: uma imediata, uma cinco minutos depois de uma falha e outra quinze minutos depois dessa. Qualquer status que não seja 2xx, erro de rede ou resposta mais lenta que dez segundos conta como falha. Depois da terceira, a entrega fica marcada como falha até você clicar em Retry.
Qual é a diferença entre X-Elido-Signature e X-Webhook-Signature?
Nenhuma além do nome. Os dois headers carregam a mesma assinatura v1=. X-Elido-Signature é o principal, e X-Webhook-Signature é mantido como alias de compatibilidade retroativa, então use o primeiro em código novo. Durante uma rotação de segredo, o Elido também envia X-Elido-Signature-Previous, assinado com o segredo antigo, por sete dias.
Como evito processar o mesmo webhook duas vezes?
Guarde o valor do header X-Webhook-Delivery e ignore qualquer requisição cujo valor você já tenha tratado. Ele identifica uma entrega a um endpoint e permanece o mesmo entre novas tentativas automáticas e reenvios manuais, então um índice único sobre ele basta.
Quem pode criar ou excluir webhooks em um workspace?
Admins e owners do workspace. Listar endpoints e ler o log de entregas exige acesso de visualização; criar, editar, excluir, rotacionar um segredo ou reenviar uma entrega exige a permissão workspace.edit. As chaves de API são limitadas ao papel escolhido quando a chave foi criada.
Experimente Elido
Cole uma URL, obtenha um link curto
Sem cadastro. O link vive 30 dias. Cadastre-se para mantê-lo para sempre.
É necessária uma conta grátis. O plano grátis inclui 25 links no total. Já tem uma conta? Entrar