Construir um produto em público não significa expor código privado, dados de clientes ou decisões que ainda precisam amadurecer. Significa compartilhar o problema, os limites e os aprendizados que podem ajudar outras pessoas.
É isso que pretendo fazer com o GitHub DevLog AI: uma central privada para receber, validar e investigar webhooks do GitHub.
Criar uma rota que receba um webhook é fácil. A dificuldade aparece quando algo falha e precisamos responder perguntas simples:
X-Hub-Signature-256
foi validada?Em desenvolvimento, normalmente olhamos o terminal, adicionamos logs temporários ou usamos um RequestBin público. Isso ajuda no primeiro teste, mas perde valor quando a integração precisa de histórico, privacidade e contexto compartilhado.
O produto nasceu dessa diferença entre receber um webhook e conseguir explicar o que aconteceu com ele.
Cada conta recebe um workspace privado com endpoint e secret próprios. O GitHub envia eventos como push
, pull_request
, issues
e workflow_run
; o sistema valida a assinatura, associa a entrega ao workspace correto e apresenta o evento em um painel de investigação.
O núcleo atual inclui:
Não é apenas uma caixa de entrada. É uma fronteira de confiança entre uma origem externa e o restante da aplicação.
Payloads de webhook podem conter nomes de repositórios, usuários, branches, mensagens de commit e outros dados operacionais. Por isso, um endpoint sem isolamento adequado transforma uma ferramenta de debugging em risco de vazamento.
O workspace não é apenas uma organização visual. Ele participa das consultas, da autorização e da resolução do endpoint. Um usuário não deve conseguir consultar eventos de outro, mesmo que descubra um identificador interno.
Durante uma investigação, o dado mais valioso é o que realmente chegou. Se o sistema transforma ou descarta informações cedo demais, perdemos a capacidade de explicar uma falha.
Ao mesmo tempo, guardar tudo indefinidamente também é uma má decisão. O produto precisa equilibrar:
Validar a assinatura no backend é obrigatório, mas o usuário também precisa entender o resultado. Mostrar que uma entrega foi validada — ou por que foi rejeitada — transforma segurança invisível em informação operacional.
O mesmo vale para rotação de secret. Não basta aceitar um segredo; é preciso permitir substituí-lo quando houver suspeita de exposição, sem reconstruir toda a integração.
O endpoint não deve executar todo o trabalho de forma síncrona. O fluxo mais seguro é validar, registrar um envelope mínimo, enfileirar o processamento e responder ao GitHub rapidamente.
Isso abre espaço para idempotência, reprocessamento e análise sem manter a entrega original esperando.
Construir o GHDevLog reforçou algumas ideias:
O produto ainda está evoluindo. Entre os temas em estudo estão busca, filtros, reprocessamento controlado, métricas por origem e uso de IA para resumir eventos sem substituir os dados brutos.
Vou compartilhar aqui decisões e erros desse processo sem transformar cada texto em anúncio. O objetivo é documentar o que aprendo ao construir um SaaS real.
Se você trabalha com webhooks: qual informação costuma faltar justamente quando uma integração falha?