Webhooks. Real-time events, delivered reliably.

Leia o corpo bruto da requisição como bytes (antes de qualquer parsing de JSON), compute HMAC-SHA256 sobre os bytes brutos usando o segredo compartilhado do seu endpoint, codifique o resultado em base16 (hex) e compare-o ao valor no cabeçalho X-Elido-Signature após remover o prefixo 'sha256='. Use uma função de comparação em tempo constante (ex.: hmac.compare_digest em Python, crypto.timingSafeEqual em Node.js) para evitar ataques de timing. Nunca compare a assinatura com um operador de igualdade de string padrão. Exemplos de código para Node.js, Python e Go estão em /docs/guides/webhooks#verification.

Retorne HTTP 200 (ou qualquer código de status 2xx) dentro de 30 segundos. O corpo da resposta é ignorado — você pode retornar um corpo vazio ou { ok: true }. Se seu processamento levar mais de 30 segundos, retorne 200 imediatamente e processe o evento de forma assíncrona (enfileire em uma fila interna, retorne 200, processe fora do caminho da requisição). Retornar 4xx é tratado da mesma forma que 5xx para fins de retry — ambos acionam um retry. Retorne 200 mesmo que o evento não seja relevante para sua integração (ex.: um evento link.created que você não precisa) para evitar retries desnecessários.

Todo payload de webhook inclui um campo event_id (UUID). Use-o como chave de idempotência no seu receptor: se você receber o mesmo event_id duas vezes (devido a um retry após uma falha parcial), processe-o apenas uma vez. Armazene os event_IDs recebidos em uma tabela de deduplicação com TTL de pelo menos 72 horas (a janela de retry). O payload de retry é idêntico ao original — mesmo event_id, mesmo corpo — portanto, uma simples verificação 'já vi esse event_id?' é suficiente.

Os endpoints são pausados automaticamente após 30 falhas de entrega consecutivas (não-2xx ou timeout). Isso evita que o Elido bombardeie indefinidamente um endpoint com problema. Corrija o problema subjacente (geralmente: a URL do endpoint mudou, o servidor está inativo, ou o timeout de 30 segundos está sendo excedido devido ao processamento lento), depois retome o endpoint no painel. Após retomado, o Elido não faz replay automático dos eventos que foram ignorados durante a pausa — faça o replay manualmente pelo log de entrega se precisar recuperar esses eventos.

Sim — ative o modo raw-click no endpoint. No modo raw-click, o Elido entrega eventos click.created individualmente sem janela de lote, em até 2 segundos após o clique. Esteja ciente de que um workspace movimentado pode produzir milhares de eventos por minuto no modo raw-click; certifique-se de que seu receptor consegue lidar com o throughput. Para a maioria dos casos de uso de analytics, a agregação em lote padrão de 5 segundos (até 100 cliques por payload) é suficiente e produz muito menos requisições HTTP.

Payloads de eventos individuais ficam abaixo de 10KB. Payloads de cliques em lote (modo padrão) podem conter até 100 eventos por lote, com um limite total de tamanho de payload de 100KB. Se um lote exceder 100KB, ele é dividido em múltiplas entregas automaticamente. Campos de metadados grandes em cliques (ex.: URLs de referrer longas) são truncados em 2KB por campo. Se seu receptor impõe um limite estrito de tamanho de payload, configure o modo raw-click (um evento por entrega) em vez do modo lote.

Use uma ferramenta como ngrok, Cloudflare Tunnel ou localtunnel para expor seu servidor local com uma URL HTTPS pública e, em seguida, registre essa URL como um endpoint de webhook no seu workspace de teste. Alternativamente, use o botão de test-fire de webhook no painel para enviar um payload de amostra para qualquer tipo de evento a um endpoint registrado sem acionar um evento real. O CLI do Elido (elido webhook test --event click.created --endpoint https://...) também funciona para testes locais via script.

Os eventos gerados durante uma janela de manutenção são enfileirados no Redpanda e entregues após o término da janela de manutenção. A página de status do Elido (status.elido.app) anuncia janelas de manutenção planejadas com antecedência. O SLA de entrega de webhook exclui janelas de manutenção anunciadas. Para a janela de manutenção típica de 30 a 60 minutos, a janela de retry de 72 horas significa que nenhum evento é perdido permanentemente — eles são entregues na ordem em que foram gerados assim que o endpoint estiver acessível novamente.