Skip to content

Webhook capture & inspection platform with AI-powered handler generation. Built with modern fullstack stack: Fastify + Drizzle ORM + React + TanStack. Production-ready. Open to contributions.

Notifications You must be signed in to change notification settings

RamosJSouza/webHookInspectorIA

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

10 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Webhook Inspector with AI Integration

🌐 Choose your language / Escolha seu idioma:

πŸ‡§πŸ‡· PortuguΓͺs | πŸ‡ΊπŸ‡Έ English



πŸ‡§πŸ‡· PortuguΓͺs

πŸ‘¨β€πŸ’» Autor

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

πŸ“‹ Sobre o Projeto

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

πŸ—οΈ Arquitetura

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

πŸš€ Tecnologias

Backend (/api)

  • 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

Frontend (/web)

  • 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

πŸ“¦ PrΓ©-requisitos

  • Node.js (versΓ£o 18 ou superior)
  • pnpm (versΓ£o 10.20.0)
  • Docker e Docker Compose

πŸ”§ InstalaΓ§Γ£o

  1. Clone o repositΓ³rio:
git clone <url-do-repositorio>
cd node-react
  1. Instale as dependΓͺncias:
# Instalar dependΓͺncias do workspace
pnpm install

# Ou instalar individualmente
cd api && pnpm install
cd ../web && pnpm install
  1. 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_aqui

⚠️ IMPORTANTE: A porta é 5434 (não 5433) para evitar conflito com PostgreSQL local na porta 5433.

πŸ”‘ Como obter a Google Generative AI API Key

Para usar a funcionalidade de geraΓ§Γ£o de cΓ³digo de webhook handlers, vocΓͺ precisa de uma API key do Google Generative AI:

  1. Acesse o Google AI Studio:

  2. FaΓ§a login:

    • Entre com sua conta Google
  3. Crie uma nova API Key:

    • Clique em "Create API Key"
    • Selecione um projeto Google Cloud (ou crie um novo)
    • Copie a API key gerada
  4. Adicione no arquivo .env:

    • Cole a API key no campo GOOGLE_GENERATIVE_AI_API_KEY no arquivo .env da pasta api/
  5. 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.

🐳 Docker

Subir o banco de dados PostgreSQL:

cd api
docker-compose up -d postgres

Isso iniciarΓ‘ o PostgreSQL na porta 5434 com as credenciais:

  • Host: localhost
  • Porta: 5434 (mapeada de 5432 do container)
  • Database: webhooks
  • Username: postgres
  • Password: root

πŸ—„οΈ Banco de Dados

MigraΓ§Γ΅es

Gerar migraΓ§Γ΅es:

cd api
pnpm db:generate

Aplicar migraΓ§Γ΅es:

# Via drizzle-kit (pode ter problemas de autenticaΓ§Γ£o TCP/IP no Windows)
pnpm db:migrate

# Via Docker (recomendado)
pnpm db:migrate:docker

Drizzle Studio (Interface visual do banco):

# Rodar no PC local
pnpm db:studio

# Acessar via prompt interativo do PostgreSQL
pnpm db:studio:docker

O Drizzle Studio estarΓ‘ disponΓ­vel em http://localhost:4983

Scripts disponΓ­veis:

# 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:docker

πŸš€ Executando o Projeto

Backend (API)

cd api
pnpm dev

A API estarΓ‘ disponΓ­vel em http://localhost:3333 A documentaΓ§Γ£o Swagger estarΓ‘ disponΓ­vel em http://localhost:3333/docs

Frontend (Web)

cd web
pnpm dev

O frontend estarΓ‘ disponΓ­vel em http://localhost:5173 (ou porta configurada pelo Vite)

πŸš€ Uso RΓ‘pido

1. Capturar um Webhook

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"
      }
    }
  }'

2. Visualizar Webhooks

  • Acesse http://localhost:5173 no navegador
  • Veja a lista de webhooks capturados no painel lateral
  • Clique em um webhook para ver seus detalhes completos

3. Gerar Handler Code

  • 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"

4. Deletar Webhooks

  • Passe o mouse sobre um webhook na lista
  • Clique no Γ­cone de lixeira que aparece
  • O webhook serΓ‘ removido imediatamente

πŸ“ Estrutura do Projeto

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

πŸ”Œ API Endpoints

Webhooks

Listar Webhooks

  • 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 (asc ou desc)
    • Response 200:
      {
        "webhooks": [
          {
            "id": "string",
            "name": "string",
            "pathname": "string",
            "createdAt": "ISO date"
          }
        ],
        "nextCursor": "string | null",
        "previousCursor": "string | null"
      }

Buscar Webhook por ID

  • 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

Deletar Webhook

  • 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

Gerar Handler Code

  • 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_KEY configurada no .env

Capturar Webhook

  • 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/payment capturarΓ‘ 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

🎨 Funcionalidades do Frontend

Lista de Webhooks

  • 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

Detalhes do Webhook

  • 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

GeraΓ§Γ£o de Handler Code

  • 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

Gerenciamento

  • 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

πŸ› οΈ Scripts DisponΓ­veis

Workspace Root

pnpm install  # Instalar todas as dependΓͺncias

API (/api)

pnpm 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 Studio

Web (/web)

pnpm dev      # Rodar em modo desenvolvimento
pnpm build    # Build para produΓ§Γ£o
pnpm preview  # Preview do build

πŸ“ Notas

  • 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

πŸ”’ SeguranΓ§a

⚠️ Importante:

  • 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 .env com 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 .env ao .gitignore para evitar commits acidentais

πŸ“„ LicenΓ§a

Este projeto estΓ‘ em desenvolvimento inicial.



πŸ‡ΊπŸ‡Έ English

πŸ‘¨β€πŸ’» Author

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

πŸ“‹ About the Project

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

πŸ—οΈ Architecture

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

πŸš€ Technologies

Backend (/api)

  • 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

Frontend (/web)

  • 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

πŸ“¦ Prerequisites

  • Node.js (version 18 or higher)
  • pnpm (version 10.20.0)
  • Docker and Docker Compose

πŸ”§ Installation

  1. Clone the repository:
git clone <repository-url>
cd node-react
  1. Install dependencies:
# Install workspace dependencies
pnpm install

# Or install individually
cd api && pnpm install
cd ../web && pnpm install
  1. 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_here

⚠️ IMPORTANT: The port is 5434 (not 5433) to avoid conflicts with local PostgreSQL on port 5433.

πŸ”‘ How to Get Google Generative AI API Key

To use the webhook handler code generation feature, you need a Google Generative AI API key:

  1. Access Google AI Studio:

  2. Sign in:

    • Sign in with your Google account
  3. Create a new API Key:

    • Click "Create API Key"
    • Select a Google Cloud project (or create a new one)
    • Copy the generated API key
  4. Add to .env file:

    • Paste the API key in the GOOGLE_GENERATIVE_AI_API_KEY field in the .env file in the api/ folder
  5. 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.

🐳 Docker

Start PostgreSQL database:

cd api
docker-compose up -d postgres

This will start PostgreSQL on port 5434 with credentials:

  • Host: localhost
  • Port: 5434 (mapped from container's 5432)
  • Database: webhooks
  • Username: postgres
  • Password: root

πŸ—„οΈ Database

Migrations

Generate migrations:

cd api
pnpm db:generate

Apply migrations:

# Via drizzle-kit (may have TCP/IP authentication issues on Windows)
pnpm db:migrate

# Via Docker (recommended)
pnpm db:migrate:docker

Drizzle Studio (Visual database interface):

# Run on local PC
pnpm db:studio

# Access via PostgreSQL interactive prompt
pnpm db:studio:docker

Drizzle Studio will be available at http://localhost:4983

Available scripts:

# 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:docker

πŸš€ Running the Project

Backend (API)

cd api
pnpm dev

The API will be available at http://localhost:3333 Swagger documentation will be available at http://localhost:3333/docs

Frontend (Web)

cd web
pnpm dev

The frontend will be available at http://localhost:5173 (or port configured by Vite)

πŸš€ Quick Usage

1. Capture a Webhook

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"
      }
    }
  }'

2. View Webhooks

  • Access http://localhost:5173 in your browser
  • See the list of captured webhooks in the side panel
  • Click on a webhook to see its complete details

3. Generate Handler Code

  • 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

4. Delete Webhooks

  • Hover over a webhook in the list
  • Click the trash icon that appears
  • The webhook will be immediately removed

πŸ“ Project Structure

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

πŸ”Œ API Endpoints

Webhooks

List Webhooks

  • 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 (asc or desc)
    • Response 200:
      {
        "webhooks": [
          {
            "id": "string",
            "name": "string",
            "pathname": "string",
            "createdAt": "ISO date"
          }
        ],
        "nextCursor": "string | null",
        "previousCursor": "string | null"
      }

Get Webhook by ID

  • 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

Delete Webhook

  • DELETE /api/webhooks/:id - Deletes a specific webhook
    • Params:
      • id (required): Webhook UUID
    • Response 204: Webhook deleted successfully
    • Response 404: Webhook not found

Generate Handler Code

  • 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_KEY configured in .env

Capture Webhook

  • 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/payment will 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

🎨 Frontend Features

Webhook List

  • 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

Webhook Details

  • 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

Handler Code Generation

  • 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

Management

  • 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

πŸ› οΈ Available Scripts

Workspace Root

pnpm install  # Install all dependencies

API (/api)

pnpm 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 Studio

Web (/web)

pnpm dev      # Run in development mode
pnpm build    # Build for production
pnpm preview  # Preview the build

πŸ“ Notes

  • 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

πŸ”’ Security

⚠️ Important:

  • Database credentials in docker-compose are for development. In production, use secure environment variables
  • Never commit .env files with real credentials to version control
  • GOOGLE_GENERATIVE_AI_API_KEY is 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 .env to .gitignore to avoid accidental commits

πŸ“„ License

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

About

Webhook capture & inspection platform with AI-powered handler generation. Built with modern fullstack stack: Fastify + Drizzle ORM + React + TanStack. Production-ready. Open to contributions.

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published