Webhooks

O polling de API faz com que o sistema receptor pergunte repetidamente ao sistema de origem "algo mudou?" em intervalos fixos (a cada 1 minuto, a cada 5 minutos). Isso é ineficiente: a maioria das requisições de polling retorna "nenhuma mudança", consumindo cota de API e criando latência (a latência máxima é igual ao intervalo de polling). Webhooks invertem o modelo: o sistema de origem notifica o receptor no instante em que um evento ocorre, alcançando latência próxima de zero sem chamadas de API desperdiçadas. A limitação é a confiabilidade: webhooks são "fire and forget" por padrão — se o sistema receptor estiver inativo, os eventos são perdidos. Sistemas de webhook bem projetados adicionam lógica de retry com exponential backoff (tentando a entrega várias vezes em intervalos crescentes) e logs de entrega (visíveis na UI do produto para que os clientes possam inspecionar se seu endpoint recebeu cada evento e investigar falhas).

Falhas de webhook estão entre os tickets de suporte de integração mais complexos porque abrangem ambos os lados da integração. Cenários comuns: (1) Endpoint não recebendo eventos — verifique se a URL do endpoint é publicamente acessível (não localhost), se o servidor aceitou o evento de teste e se o tipo de evento está inscrito. (2) Resposta HTTP 200 não retornada — o servidor receptor deve retornar um status HTTP 200 dentro da janela de timeout (geralmente 10–30 segundos); se demorar mais, a plataforma de webhook marca a entrega como falha, mesmo que o servidor tenha processado o evento. (3) Eventos duplicados — consumidores de webhook bem projetados devem ser idempotentes (processar o mesmo evento duas vezes produz o mesmo resultado que processá-lo uma vez) usando o ID único do evento para detectar e ignorar duplicatas. (4) Falha na verificação de assinatura — a maioria das APIs SaaS assina os payloads de webhook com HMAC-SHA256 usando uma chave secreta; o código do cliente deve verificar esta assinatura em cada evento recebido para prevenir ataques de webhook falsificados.

Product Ops colabora com a Engenharia para projetar capacidades de webhook que minimizem a carga de suporte e maximizem a satisfação do desenvolvedor. Melhores práticas: cobertura de tipos de evento (toda mudança de estado significativa no produto deve ter um evento de webhook correspondente); design do payload do evento (payloads devem incluir todos os dados necessários para agir sobre o evento sem uma chamada de API de acompanhamento — inclua o estado completo do objeto, não apenas IDs que exigem uma requisição GET subsequente); UI de logs de entrega (um log de eventos pesquisável no dashboard do produto onde os desenvolvedores podem ver cada evento disparado, seu status de entrega, a resposta HTTP do servidor e um botão de "redeliver" para nova tentativa manual); verificação de assinatura (assine cada payload com HMAC-SHA256 e documente o processo de verificação claramente); e payloads versionados (quando o esquema do evento precisar mudar, versione o payload e suporte ambas as versões simultaneamente durante um período de transição — nunca faça mudanças que quebrem a compatibilidade em um payload de webhook sem aviso prévio).