O que estou construindo com o GitHub DevLog AI

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.

O problema não era receber o POST

Criar uma rota que receba um webhook é fácil. A dificuldade aparece quando algo falha e precisamos responder perguntas simples:

• O GitHub realmente enviou o evento?
• Qual repositório e tipo de evento estavam envolvidos?
• A assinatura X-Hub-Signature-256 foi validada?
• O payload chegou completo?
• A entrega foi duplicada?
• Quem pode consultar esses dados?

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.

A proposta do GHDevLog

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:

• cadastro e autenticação;
• workspace isolado por conta;
• endpoint exclusivo;
• secret com possibilidade de rotação;
• validação HMAC SHA-256;
• histórico de eventos;
• visualização do payload e dos headers relevantes.

Não é apenas uma caixa de entrada. É uma fronteira de confiança entre uma origem externa e o restante da aplicação.

Decisão 1: privado por padrã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.

Decisão 2: preservar o evento antes de interpretá-lo demais

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:

• fidelidade do evento;
• minimização de dados;
• política de retenção;
• proteção de informações sensíveis;
• custo de armazenamento.

Decisão 3: segurança precisa aparecer no produto

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.

Decisão 4: responder rápido e processar depois

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.

O que estou aprendendo

Construir o GHDevLog reforçou algumas ideias:

1. Observabilidade é parte do produto, não um painel adicionado no fim.
2. Multi-tenancy precisa alcançar banco, logs, filas, cache e exports.
3. Segurança útil é aquela que também ajuda a diagnosticar.
4. Um bom produto para desenvolvedores reduz tempo de investigação, não apenas número de cliques.
5. A primeira versão deve resolver o fluxo principal antes de acumular integrações.

Próximos passos

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?