Ramos (Ramos) de Souza Janones | He/Him
Desenvolvedor Full Stack Pleno | Node.js com backend, React, Next.js, Angular, Ionic como frontend, TypeScript | DevOps, AWS, Azure, IA | LideranΓ§a tΓ©cnica
π LinkedIn
Este Γ© um sistema completo de inspeΓ§Γ£o e gerenciamento de webhooks com integraΓ§Γ£o de IA para geraΓ§Γ£o automΓ‘tica de cΓ³digo TypeScript. O projeto permite:
- Capturar webhooks de qualquer origem atravΓ©s de um endpoint universal
- Visualizar detalhes completos de cada webhook recebido (headers, body, query params, etc.)
- Gerenciar webhooks com funcionalidades de listagem, busca e exclusΓ£o
- Gerar cΓ³digo automaticamente usando IA (Google Gemini) para criar handlers TypeScript production-ready baseados nos webhooks capturados
- Interface moderna com React, TanStack Router e componentes acessΓveis
O projeto utiliza uma arquitetura monorepo com:
- API (
/api): Backend em Node.js com Fastify, TypeScript e Drizzle ORM - Web (
/web): Frontend em React com Vite e TypeScript
- Node.js com TypeScript
- Fastify - Framework web rΓ‘pido e eficiente
- Drizzle ORM - ORM moderno para PostgreSQL
- PostgreSQL - Banco de dados relacional
- Docker - ContainerizaΓ§Γ£o do banco de dados
- Zod - ValidaΓ§Γ£o de schemas
- Fastify Swagger - DocumentaΓ§Γ£o da API
- AI SDK - IntegraΓ§Γ£o com Google Gemini para geraΓ§Γ£o de cΓ³digo
- @ai-sdk/google - SDK oficial do Google para Generative AI
- React - Biblioteca para construΓ§Γ£o de interfaces
- Vite - Build tool e dev server
- TypeScript - Tipagem estΓ‘tica
- TanStack Router - Roteamento type-safe
- TanStack Query - Gerenciamento de estado servidor
- Radix UI - Componentes acessΓveis (Dialog, Checkbox)
- Tailwind CSS - Framework CSS utilitΓ‘rio
- Shiki - Syntax highlighting para cΓ³digo
- date-fns - ManipulaΓ§Γ£o de datas
- Lucide React - Γcones
- Node.js (versΓ£o 18 ou superior)
- pnpm (versΓ£o 10.20.0)
- Docker e Docker Compose
- Clone o repositΓ³rio:
git clone <url-do-repositorio>
cd node-react- Instale as dependΓͺncias:
# Instalar dependΓͺncias do workspace
pnpm install
# Ou instalar individualmente
cd api && pnpm install
cd ../web && pnpm install- Configure as variΓ‘veis de ambiente:
Crie um arquivo .env na pasta api/:
DATABASE_URL=postgresql://postgres:root@localhost:5434/webhooks
PORT=3333
NODE_ENV=development
GOOGLE_GENERATIVE_AI_API_KEY=sua_api_key_aquiPara usar a funcionalidade de geraΓ§Γ£o de cΓ³digo de webhook handlers, vocΓͺ precisa de uma API key do Google Generative AI:
-
Acesse o Google AI Studio:
-
FaΓ§a login:
- Entre com sua conta Google
-
Crie uma nova API Key:
- Clique em "Create API Key"
- Selecione um projeto Google Cloud (ou crie um novo)
- Copie a API key gerada
-
Adicione no arquivo
.env:- Cole a API key no campo
GOOGLE_GENERATIVE_AI_API_KEYno arquivo.envda pastaapi/
- Cole a API key no campo
-
ConfiguraΓ§Γ΅es de seguranΓ§a (recomendado):
- No Google Cloud Console, vocΓͺ pode restringir a API key para uso apenas com a API do Generative AI
- Configure limites de uso para evitar cobranΓ§as inesperadas
π Nota: A API key Γ© necessΓ‘ria apenas para a funcionalidade de geraΓ§Γ£o de cΓ³digo. As outras funcionalidades (listar, visualizar, deletar webhooks) funcionam sem ela.
cd api
docker-compose up -d postgresIsso iniciarΓ‘ o PostgreSQL na porta 5434 com as credenciais:
- Host:
localhost - Porta:
5434(mapeada de 5432 do container) - Database:
webhooks - Username:
postgres - Password:
root
cd api
pnpm db:generate# Via drizzle-kit (pode ter problemas de autenticaΓ§Γ£o TCP/IP no Windows)
pnpm db:migrate
# Via Docker (recomendado)
pnpm db:migrate:docker# Rodar no PC local
pnpm db:studio
# Acessar via prompt interativo do PostgreSQL
pnpm db:studio:dockerO Drizzle Studio estarΓ‘ disponΓvel em http://localhost:4983
# Gerar migraΓ§Γ΅es baseadas no schema
pnpm db:generate
# Aplicar migraΓ§Γ΅es (via drizzle-kit)
pnpm db:migrate
# Aplicar migraΓ§Γ΅es (via Docker - recomendado)
pnpm db:migrate:docker
# Abrir Drizzle Studio
pnpm db:studio
# Abrir prompt PostgreSQL interativo
pnpm db:studio:dockercd api
pnpm devA API estarΓ‘ disponΓvel em http://localhost:3333
A documentaΓ§Γ£o Swagger estarΓ‘ disponΓvel em http://localhost:3333/docs
cd web
pnpm devO frontend estarΓ‘ disponΓvel em http://localhost:5173 (ou porta configurada pelo Vite)
Envie uma requisiΓ§Γ£o para o endpoint de captura:
# Exemplo: Capturar um webhook do Stripe
curl -X POST http://localhost:3333/capture/stripe/payment \
-H "Content-Type: application/json" \
-d '{
"type": "payment_intent.succeeded",
"data": {
"object": {
"id": "pi_123",
"amount": 1000,
"currency": "usd"
}
}
}'- Acesse
http://localhost:5173no navegador - Veja a lista de webhooks capturados no painel lateral
- Clique em um webhook para ver seus detalhes completos
- Selecione um ou mais webhooks usando os checkboxes
- Clique em "Handle Generator"
- Aguarde a geraΓ§Γ£o do cΓ³digo (pode levar alguns segundos)
- Copie o cΓ³digo gerado usando o botΓ£o "Copy Code"
- Passe o mouse sobre um webhook na lista
- Clique no Γcone de lixeira que aparece
- O webhook serΓ‘ removido imediatamente
node-react/
βββ api/ # Backend
β βββ src/
β β βββ db/ # ConfiguraΓ§Γ£o do banco de dados
β β β βββ migrations/ # MigraΓ§Γ΅es SQL
β β β βββ schema/ # Schemas Drizzle ORM
β β βββ routes/ # Rotas da API
β β βββ lib/ # Bibliotecas e utilitΓ‘rios
β β βββ env.ts # ValidaΓ§Γ£o de variΓ‘veis de ambiente
β β βββ server.ts # Arquivo principal do servidor
β βββ docker-compose.yaml # ConfiguraΓ§Γ£o Docker
β βββ drizzle.config.ts # ConfiguraΓ§Γ£o do Drizzle
β βββ package.json
βββ web/ # Frontend
β βββ src/
β β βββ app.tsx
β β βββ main.tsx
β β βββ index.css
β βββ package.json
βββ package.json # Workspace root
GET /api/webhooks- Lista todos os webhooks recebidos com paginaΓ§Γ£o por cursor- Query params:
limit(opcional, padrΓ£o: 20): Limite de resultados por pΓ‘gina (1-100)cursor(opcional): ID do ΓΊltimo webhook da pΓ‘gina anterior (para paginaΓ§Γ£o)orderBy(opcional): Campo para ordenaΓ§Γ£o (createdAt)orderDirection(opcional): DireΓ§Γ£o da ordenaΓ§Γ£o (ascoudesc)
- Response 200:
{ "webhooks": [ { "id": "string", "name": "string", "pathname": "string", "createdAt": "ISO date" } ], "nextCursor": "string | null", "previousCursor": "string | null" }
- Query params:
GET /api/webhooks/:id- Busca um webhook especΓfico pelo ID- Params:
id(obrigatΓ³rio): UUID do webhook
- Response 200: Objeto completo do webhook com todos os detalhes (headers, body, query params, etc.)
- Response 404: Webhook nΓ£o encontrado
- Params:
DELETE /api/webhooks/:id- Deleta um webhook especΓfico- Params:
id(obrigatΓ³rio): UUID do webhook
- Response 204: Webhook deletado com sucesso
- Response 404: Webhook nΓ£o encontrado
- Params:
POST /api/generate- Gera cΓ³digo TypeScript de handler para webhooks selecionados usando IA- Body:
{ "webhookIds": ["id1", "id2", "id3"] } - Response 201:
{ "code": "cΓ³digo TypeScript gerado" } - Response 400: Nenhum ID de webhook fornecido
- Requires:
GOOGLE_GENERATIVE_AI_API_KEYconfigurada no.env
- Body:
ALL /capture/*- Captura qualquer requisiΓ§Γ£o webhook enviada para este endpoint- Uso: Este endpoint captura requisiΓ§Γ΅es de qualquer mΓ©todo HTTP (GET, POST, PUT, DELETE, etc.)
- Exemplo:
POST http://localhost:3333/capture/stripe/paymentcapturarΓ‘ a requisiΓ§Γ£o - Response 201:
{ "id": "uuid-do-webhook-capturado" } - Dados capturados:
- Headers HTTP
- Body da requisiΓ§Γ£o
- Query parameters
- IP do remetente
- MΓ©todo HTTP
- Pathname
- Content-Type e Content-Length
- PaginaΓ§Γ£o por cursor: Carregue mais webhooks com o botΓ£o "Load more"
- SeleΓ§Γ£o mΓΊltipla: Marque vΓ‘rios webhooks usando checkboxes
- VisualizaΓ§Γ£o em tempo real: Veja todos os webhooks capturados em uma lista organizada
- InformaΓ§Γ΅es exibidas: MΓ©todo HTTP, pathname e tempo relativo de captura
- VisualizaΓ§Γ£o completa: Veja todos os detalhes de um webhook especΓfico
- Request Overview: MΓ©todo, status code, content type e content length
- Query Parameters: Visualize todos os parΓ’metros de query da requisiΓ§Γ£o
- Headers: Lista completa de headers HTTP recebidos
- Request Body: Body da requisiΓ§Γ£o formatado e destacado
- InformaΓ§Γ΅es adicionais: IP do remetente e timestamp de captura
- SeleΓ§Γ£o mΓΊltipla: Selecione vΓ‘rios webhooks para gerar um handler completo
- IA integrada: Usa Google Gemini para gerar cΓ³digo TypeScript production-ready
- CΓ³digo tipado: Gera handlers com validaΓ§Γ£o Zod e tipos TypeScript
- Syntax highlighting: VisualizaΓ§Γ£o do cΓ³digo com destaque de sintaxe
- Copiar cΓ³digo: BotΓ£o para copiar o cΓ³digo gerado para a Γ‘rea de transferΓͺncia
- Loading state: Indicador visual durante a geraΓ§Γ£o do cΓ³digo
- Deletar webhooks: Remova webhooks individuais diretamente da lista
- Interface responsiva: Layout adaptΓ‘vel com painΓ©is redimensionΓ‘veis
- Feedback visual: Estados de loading, sucesso e erro claramente indicados
pnpm install # Instalar todas as dependΓͺnciaspnpm dev # Rodar em modo desenvolvimento
pnpm start # Rodar em modo produΓ§Γ£o
pnpm format # Formatar cΓ³digo com Biome
pnpm db:generate # Gerar migraΓ§Γ΅es
pnpm db:migrate # Aplicar migraΓ§Γ΅es
pnpm db:studio # Abrir Drizzle Studiopnpm dev # Rodar em modo desenvolvimento
pnpm build # Build para produΓ§Γ£o
pnpm preview # Preview do build- O projeto utiliza pnpm workspaces para gerenciar dependΓͺncias
- O banco de dados PostgreSQL roda via Docker para facilitar o setup
- As migraΓ§Γ΅es podem ser aplicadas via Docker para evitar problemas de autenticaΓ§Γ£o TCP/IP no Windows
- A geraΓ§Γ£o de cΓ³digo via IA requer uma API key vΓ‘lida do Google Generative AI
- O modelo usado para geraΓ§Γ£o Γ© o
gemini-2.0-flash-lite(rΓ‘pido e eficiente) - Todos os endpoints da API estΓ£o documentados no Swagger disponΓvel em
/docs
- As credenciais do banco de dados no docker-compose sΓ£o para desenvolvimento. Em produΓ§Γ£o, use variΓ‘veis de ambiente seguras
- Nunca commite arquivos
.envcom credenciais reais no controle de versΓ£o - A
GOOGLE_GENERATIVE_AI_API_KEYΓ© sensΓvel e deve ser mantida em segredo - Configure restriΓ§Γ΅es na API key do Google Cloud para limitar o uso apenas ao necessΓ‘rio
- Em produΓ§Γ£o, use um gerenciador de segredos (AWS Secrets Manager, Azure Key Vault, etc.)
- Adicione
.envao.gitignorepara evitar commits acidentais
Este projeto estΓ‘ em desenvolvimento inicial.
Ramos (Ramos) de Souza Janones | He/Him
Full Stack Mid-level Developer | Node.js with backend, React, Next.js, Angular, Ionic as frontend, TypeScript | DevOps, AWS, Azure, AI | Technical Leadership
π LinkedIn
This is a complete webhook inspection and management system with AI integration for automatic TypeScript code generation. The project enables:
- Capture webhooks from any source through a universal endpoint
- View complete details of each received webhook (headers, body, query params, etc.)
- Manage webhooks with listing, search, and deletion features
- Automatically generate code using AI (Google Gemini) to create production-ready TypeScript handlers based on captured webhooks
- Modern interface with React, TanStack Router, and accessible components
The project uses a monorepo architecture with:
- API (
/api): Backend in Node.js with Fastify, TypeScript, and Drizzle ORM - Web (
/web): Frontend in React with Vite and TypeScript
- Node.js with TypeScript
- Fastify - Fast and efficient web framework
- Drizzle ORM - Modern ORM for PostgreSQL
- PostgreSQL - Relational database
- Docker - Database containerization
- Zod - Schema validation
- Fastify Swagger - API documentation
- AI SDK - Integration with Google Gemini for code generation
- @ai-sdk/google - Official Google SDK for Generative AI
- React - Library for building interfaces
- Vite - Build tool and dev server
- TypeScript - Static typing
- TanStack Router - Type-safe routing
- TanStack Query - Server state management
- Radix UI - Accessible components (Dialog, Checkbox)
- Tailwind CSS - Utility CSS framework
- Shiki - Syntax highlighting for code
- date-fns - Date manipulation
- Lucide React - Icons
- Node.js (version 18 or higher)
- pnpm (version 10.20.0)
- Docker and Docker Compose
- Clone the repository:
git clone <repository-url>
cd node-react- Install dependencies:
# Install workspace dependencies
pnpm install
# Or install individually
cd api && pnpm install
cd ../web && pnpm install- Configure environment variables:
Create a .env file in the api/ folder:
DATABASE_URL=postgresql://postgres:root@localhost:5434/webhooks
PORT=3333
NODE_ENV=development
GOOGLE_GENERATIVE_AI_API_KEY=your_api_key_hereTo use the webhook handler code generation feature, you need a Google Generative AI API key:
-
Access Google AI Studio:
-
Sign in:
- Sign in with your Google account
-
Create a new API Key:
- Click "Create API Key"
- Select a Google Cloud project (or create a new one)
- Copy the generated API key
-
Add to
.envfile:- Paste the API key in the
GOOGLE_GENERATIVE_AI_API_KEYfield in the.envfile in theapi/folder
- Paste the API key in the
-
Security settings (recommended):
- In Google Cloud Console, you can restrict the API key to use only the Generative AI API
- Configure usage limits to avoid unexpected charges
π Note: The API key is only required for the code generation feature. Other features (list, view, delete webhooks) work without it.
cd api
docker-compose up -d postgresThis will start PostgreSQL on port 5434 with credentials:
- Host:
localhost - Port:
5434(mapped from container's 5432) - Database:
webhooks - Username:
postgres - Password:
root
cd api
pnpm db:generate# Via drizzle-kit (may have TCP/IP authentication issues on Windows)
pnpm db:migrate
# Via Docker (recommended)
pnpm db:migrate:docker# Run on local PC
pnpm db:studio
# Access via PostgreSQL interactive prompt
pnpm db:studio:dockerDrizzle Studio will be available at http://localhost:4983
# Generate migrations based on schema
pnpm db:generate
# Apply migrations (via drizzle-kit)
pnpm db:migrate
# Apply migrations (via Docker - recommended)
pnpm db:migrate:docker
# Open Drizzle Studio
pnpm db:studio
# Open PostgreSQL interactive prompt
pnpm db:studio:dockercd api
pnpm devThe API will be available at http://localhost:3333
Swagger documentation will be available at http://localhost:3333/docs
cd web
pnpm devThe frontend will be available at http://localhost:5173 (or port configured by Vite)
Send a request to the capture endpoint:
# Example: Capture a Stripe webhook
curl -X POST http://localhost:3333/capture/stripe/payment \
-H "Content-Type: application/json" \
-d '{
"type": "payment_intent.succeeded",
"data": {
"object": {
"id": "pi_123",
"amount": 1000,
"currency": "usd"
}
}
}'- Access
http://localhost:5173in your browser - See the list of captured webhooks in the side panel
- Click on a webhook to see its complete details
- Select one or more webhooks using checkboxes
- Click "Handle Generator"
- Wait for code generation (may take a few seconds)
- Copy the generated code using the "Copy Code" button
- Hover over a webhook in the list
- Click the trash icon that appears
- The webhook will be immediately removed
node-react/
βββ api/ # Backend
β βββ src/
β β βββ db/ # Database configuration
β β β βββ migrations/ # SQL migrations
β β β βββ schema/ # Drizzle ORM schemas
β β βββ routes/ # API routes
β β βββ lib/ # Libraries and utilities
β β βββ env.ts # Environment variables validation
β β βββ server.ts # Main server file
β βββ docker-compose.yaml # Docker configuration
β βββ drizzle.config.ts # Drizzle configuration
β βββ package.json
βββ web/ # Frontend
β βββ src/
β β βββ app.tsx
β β βββ main.tsx
β β βββ index.css
β βββ package.json
βββ package.json # Workspace root
GET /api/webhooks- Lists all received webhooks with cursor-based pagination- Query params:
limit(optional, default: 20): Results per page (1-100)cursor(optional): ID of the last webhook from the previous page (for pagination)orderBy(optional): Field for sorting (createdAt)orderDirection(optional): Sort direction (ascordesc)
- Response 200:
{ "webhooks": [ { "id": "string", "name": "string", "pathname": "string", "createdAt": "ISO date" } ], "nextCursor": "string | null", "previousCursor": "string | null" }
- Query params:
GET /api/webhooks/:id- Gets a specific webhook by ID- Params:
id(required): Webhook UUID
- Response 200: Complete webhook object with all details (headers, body, query params, etc.)
- Response 404: Webhook not found
- Params:
DELETE /api/webhooks/:id- Deletes a specific webhook- Params:
id(required): Webhook UUID
- Response 204: Webhook deleted successfully
- Response 404: Webhook not found
- Params:
POST /api/generate- Generates TypeScript handler code for selected webhooks using AI- Body:
{ "webhookIds": ["id1", "id2", "id3"] } - Response 201:
{ "code": "generated TypeScript code" } - Response 400: No webhook IDs provided
- Requires:
GOOGLE_GENERATIVE_AI_API_KEYconfigured in.env
- Body:
ALL /capture/*- Captures any webhook request sent to this endpoint- Usage: This endpoint captures requests of any HTTP method (GET, POST, PUT, DELETE, etc.)
- Example:
POST http://localhost:3333/capture/stripe/paymentwill capture the request - Response 201:
{ "id": "captured-webhook-uuid" } - Captured data:
- HTTP Headers
- Request body
- Query parameters
- Sender IP
- HTTP method
- Pathname
- Content-Type and Content-Length
- Cursor pagination: Load more webhooks with the "Load more" button
- Multiple selection: Mark multiple webhooks using checkboxes
- Real-time visualization: See all captured webhooks in an organized list
- Displayed information: HTTP method, pathname, and relative capture time
- Complete visualization: See all details of a specific webhook
- Request Overview: Method, status code, content type, and content length
- Query Parameters: View all query parameters from the request
- Headers: Complete list of received HTTP headers
- Request Body: Formatted and highlighted request body
- Additional information: Sender IP and capture timestamp
- Multiple selection: Select multiple webhooks to generate a complete handler
- AI integrated: Uses Google Gemini to generate production-ready TypeScript code
- Typed code: Generates handlers with Zod validation and TypeScript types
- Syntax highlighting: Code visualization with syntax highlighting
- Copy code: Button to copy generated code to clipboard
- Loading state: Visual indicator during code generation
- Delete webhooks: Remove individual webhooks directly from the list
- Responsive interface: Adaptive layout with resizable panels
- Visual feedback: Loading, success, and error states clearly indicated
pnpm install # Install all dependenciespnpm dev # Run in development mode
pnpm start # Run in production mode
pnpm format # Format code with Biome
pnpm db:generate # Generate migrations
pnpm db:migrate # Apply migrations
pnpm db:studio # Open Drizzle Studiopnpm dev # Run in development mode
pnpm build # Build for production
pnpm preview # Preview the build- The project uses pnpm workspaces to manage dependencies
- PostgreSQL database runs via Docker to facilitate setup
- Migrations can be applied via Docker to avoid TCP/IP authentication issues on Windows
- AI code generation requires a valid Google Generative AI API key
- The model used for generation is
gemini-2.0-flash-lite(fast and efficient) - All API endpoints are documented in Swagger available at
/docs
- Database credentials in docker-compose are for development. In production, use secure environment variables
- Never commit
.envfiles with real credentials to version control GOOGLE_GENERATIVE_AI_API_KEYis sensitive and must be kept secret- Configure restrictions on the Google Cloud API key to limit usage to only what's necessary
- In production, use a secrets manager (AWS Secrets Manager, Azure Key Vault, etc.)
- Add
.envto.gitignoreto avoid accidental commits
This project is in initial development.
β¬οΈ Back to top | π§π· PortuguΓͺs
Desenvolvido com β€οΈ por Ramos de Souza Janones | Developed with β€οΈ by Ramos de Souza Janones