Webhook e Arquitetura Orientada a Eventos para SaaS

Webhooks implementam um modelo de "push": quando um evento de gatilho ocorre no produto SaaS (um novo ticket é criado, uma assinatura é renovada, o status da conta de um usuário muda), o produto faz uma requisição HTTP POST para uma URL configurada pelo cliente, entregando o payload do evento em tempo real. Polling (a alternativa) envolve o sistema do cliente fazendo requisições GET periódicas à API para verificar se algo mudou — verificar a cada 5 minutos significa que os eventos podem ter até 5 minutos de atraso, e o polling constante cria uma carga desnecessária na API, independentemente de os eventos estarem ocorrendo. Vantagens do Webhook: entrega em tempo real (notificação de evento em milissegundos após a ação de gatilho); zero sobrecarga de polling (nenhuma chamada de API desperdiçada em períodos de inatividade); menor consumo de limite de taxa da API (eventos de webhook não contam para as cotas de requisição); e código de integração mais simples (o cliente escreve uma função de handler em vez de um loop de polling com gerenciamento de estado). Limitações do Webhook: o cliente deve executar um endpoint HTTPS público para receber eventos (requisito de infraestrutura); a entrega de eventos pode falhar se o endpoint receptor estiver inativo (exigindo um mecanismo robusto de retentativa do provedor); e garantias de ordenação geralmente não são fornecidas (os eventos podem chegar ligeiramente fora de ordem sob alta carga). Uma infraestrutura de webhook bem projetada aborda essas limitações através de retentativa com backoff exponencial, metadados de ordenação de eventos (números de sequência ou timestamps) e um log de webhook acessível através do dashboard para depurar eventos perdidos.

A confiabilidade do webhook é medida pela taxa de entrega — a porcentagem de eventos gerados que são entregues com sucesso aos endpoints do cliente. Taxas de entrega abaixo de 99% tornam os webhooks não confiáveis para integrações de produção. Requisitos de engenharia de confiabilidade: Retentativa de entrega com backoff exponencial: se o endpoint do cliente retornar uma resposta não-2XX ou expirar, o provedor tenta a entrega novamente com intervalos crescentes (retentativa em 1 min, 5 min, 30 min, 2 horas, 24 horas). Após a sequência de retentativas se esgotar, o evento é marcado como "falhou" e visível no log de entrega do webhook. Idempotência: cada entrega de evento de webhook inclui um ID de evento único, permitindo que os sistemas do cliente detectem e descartem com segurança entregas duplicadas (garantindo que a entrega "pelo menos uma vez" — eventos são enviados pelo menos uma vez — não produza processamento de dados duplicados). Versionamento de payload: a estrutura do payload do webhook deve ser versionada explicitamente para que mudanças que quebram a compatibilidade no formato do payload não quebrem silenciosamente as integrações do cliente. Uma estratégia de versionamento de webhook permite que os clientes recebam o formato antigo por uma janela de depreciação enquanto migram para o novo formato. Logs de entrega do cliente: fornecem uma visão no dashboard do histórico de entrega de cada endpoint de webhook — timestamp, código de resposta HTTP, latência de entrega e contagem de retentativas. Clientes que depuram problemas de integração precisam dessa visibilidade sem a necessidade de contato com o suporte. Alerta de saúde de entrega: notificar proativamente os clientes quando seu endpoint de webhook tiver falhas sustentadas (>10 falhas de entrega consecutivas) via e-mail, permitindo que eles corrijam seu endpoint antes que percam eventos críticos.

Um catálogo de eventos de webhook é a lista abrangente de eventos que o produto pode emitir, cada um com seu significado semântico, condições de gatilho e documentação da estrutura do payload. Convenções de nomenclatura de eventos: um esquema de nomenclatura de eventos deve ser consistente, legível e autoexplicativo — o padrão recurso:ação é o mais comum e limpo. Exemplos: ticket.created, ticket.status_changed, subscription.renewed, user.role_updated, account.churned. Evite nomes de eventos ambíguos (ticket.updated — o que mudou?); prefira eventos específicos (ticket.priority_changed, ticket.assignee_changed). Design de granularidade: incline-se para eventos mais granulares em vez de menos. Clientes que constroem integrações podem escolher a quais eventos se inscrever — eles ignorarão eventos que não se aplicam ao seu caso de uso, mas não podem construir uma integração confiável se sua condição de gatilho exata for agrupada com eventos irrelevantes em um evento genérico "ticket.updated". Design do payload: cada payload de evento deve incluir: o tipo de evento (string), o ID do evento (UUID único), o timestamp (ISO 8601 UTC), o ID do recurso, o estado atual do recurso (o objeto de recurso completo após a mudança de gatilho) e — para eventos de mudança — o estado anterior do atributo alterado. Eventos solicitados pelo cliente: mantenha um backlog de solicitações de eventos de webhook de clientes e parceiros de integração. Eventos de alta solicitação com múltiplas partes solicitantes são priorizados no roadmap da API.