![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Python](https://img.shields.io/badge/python-3.13-blue?style=flat)
![Framework](https://img.shields.io/badge/FastAPI-async-green)
![Database](https://img.shields.io/badge/SQLite-persistent-lightgrey)
![UI](https://img.shields.io/badge/HTMX-realtime-orange)
![Deploy](https://img.shields.io/badge/deploy-Railway-purple)

# Webhook Catcher

> The easiest way to capture and debug webhooks in production and development.

A developer-friendly webhook debugging tool — ideal for testing GitHub/Stripe events, bot integrations, or any webhook-based workflow.  
Replay, filter, and forward webhooks in real time with zero config.

---

## Features

- Capture and view incoming webhooks in real time
- Search, filter, and export webhook logs
- Replay webhooks to any target URL
- Multi-service ready: forward webhooks to your own bot/service
- **Production-ready admin protection** for sensitive operations
- Deploy instantly on Railway or any platform

---

## 🚀 Deploy on Railway (Recommended)

⚡ **Why Railway?**

Webhook Catcher is optimized for Railway:

- 🧠 Zero config — deploy in seconds
- 🪄 Auto-generated domain (instantly test your webhook)
- 💾 Automatic persistent storage (no data loss on redeploy)
- 🔐 Built-in secret management & protection

---

## 💾 Persistent Storage (Railway)

Webhook Catcher uses SQLite for storage.

When deploying via the **Railway template**, a persistent volume is
**automatically created and mounted** — no manual setup required.

✔ Data persists across redeploys  
✔ No configuration needed  
✔ Works out of the box

---

## ✨ Sophisticated Architecture Overview

```mermaid
graph TB
    A[External Webhooks<br/>GitHub, Stripe, IoT] --> B[Load Balancer]
    B --> C[Webhook Catcher Service<br/>FastAPI + HTMX]
    C --> D[SQLite Database<br/>Persistent Volume]
    C --> E[Your Bot Service<br/>Python/Node/etc]
    E --> F[Discord/Slack/etc<br/>Notifications]
    C --> G[Real-time Web UI<br/>Live Updates]
    
    style C fill:#0ea5e9
    style E fill:#10b981
    style D fill:#f59e0b
```

---

## 🧩 Use Cases

- Debug Stripe or GitHub webhooks in production
- Build and test bots for Discord, Telegram, or Slack
- Capture IoT webhook payloads for later processing
- Replay webhooks to local dev or staging environments

---

## Quick Start

1. **Deploy on Railway:**  
   [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/webhook-catcher?referralCode=nIQTyp&utm_medium=integration&utm_source=template&utm_campaign=generic)

2. **Send a webhook:**  
   Use your deployed `/webhook` endpoint with any service or tool (e.g., GitHub, Stripe, curl).

   ```bash
   curl -X POST https://your-app.railway.app/webhook \
     -H "Content-Type: application/json" \
     -d '{"event": "test", "message": "Hello"}'
   ```

3. **View and replay webhooks:**  
   Open the web UI to see logs, search, export, or replay to another URL.

---

## Screenshots

![Main UI](assets/main.png)
![Webhook Logs](assets/logs.png)

---

## 🔧 Configuration

### Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `FORWARD_WEBHOOK_URL` | Forward incoming webhooks to another service | No | - |
| `FORWARD_WEBHOOK_TOKEN` | Authentication token for secure forwarding | No | - |
| `ADMIN_TOKEN` | **Admin protection token for sensitive operations** | No | - |
| `FRONTEND_PASSWORD` | **Password to protect the web UI from public access** | No | - |

### 🔒 Admin Protection (Production Feature)

The `ADMIN_TOKEN` environment variable provides **production-grade security** for sensitive operations:

#### Protected Operations:
- **Clear all logs** (`POST /clear`)
- **Replay webhooks** (`POST /replay/{id}`)

#### Security Modes:

**1. No Protection (Development)**
```bash
# Leave ADMIN_TOKEN empty or unset
ADMIN_TOKEN=""
```
- All operations are publicly accessible
- Perfect for development and testing

**2. Token Protection (Production)**
```bash
# Set a strong admin token
ADMIN_TOKEN="your-secret-admin-token-123"
```
- Admin operations require authentication
- Token can be provided via:
  - Header: `X-Admin-Token: your-secret-admin-token-123`
  - Query parameter: `?admin_token=your-secret-admin-token-123`

#### Usage Examples:

**Clear logs with admin token:**
```bash
# Via header (recommended)
curl -X POST "https://your-app.railway.app/clear" \
  -H "X-Admin-Token: your-secret-admin-token-123"

# Via query parameter
curl -X POST "https://your-app.railway.app/clear?admin_token=your-secret-admin-token-123"
```

**Replay webhook with admin token:**
```bash
curl -X POST "https://your-app.railway.app/replay/1?target_url=https://httpbin.org/post" \
  -H "X-Admin-Token: your-secret-admin-token-123"
```

**Health check shows protection status:**
```bash
curl https://your-app.railway.app/healthz
# Returns: {"status": "ok", "admin_protected": true}
```

#### Security Best Practices:
- Use a strong, random token (minimum 20 characters)
- Keep the token secret and rotate it regularly
- Use headers instead of query parameters when possible
- Enable admin protection for production deployments

### 🔐 Frontend Password Protection

The `FRONTEND_PASSWORD` environment variable protects the **web UI** from public access using HTTP Basic Authentication.

#### Protected Routes:
- **Home page** (`GET /`)
- **Logs view** (`GET /logs`, `GET /logs/view`)
- **Export logs** (`GET /export`)
- **List webhooks** (`GET /webhooks`)

#### Unprotected Routes (remain open):
- **Webhook receiver** (`POST /webhook`) - external services must be able to send webhooks
- **Health check** (`GET /healthz`)
- **Config status** (`GET /config`)

#### Usage:

**1. No Protection (Development)**
```bash
# Leave FRONTEND_PASSWORD empty or unset
FRONTEND_PASSWORD=""
```
- Web UI is publicly accessible
- Perfect for development and testing

**2. Password Protection (Production)**
```bash
# Set a password to protect the web UI
FRONTEND_PASSWORD="your-secret-password"
```
- Accessing the web UI prompts for HTTP Basic Auth
- Username can be anything (only password is checked)
- Browser remembers credentials for the session

#### How it works:
When `FRONTEND_PASSWORD` is set, accessing protected routes will prompt your browser's built-in HTTP Basic Auth dialog. Enter any username and the configured password to access the UI.

---

## Advanced Features

### Multi-Service Architecture
- **Internal networking**: Link your own service using `FORWARD_WEBHOOK_URL`
- **Secure forwarding**: Use `FORWARD_WEBHOOK_TOKEN` for authenticated service-to-service communication
- **Real-time processing**: Forward webhooks immediately while storing for replay

### Data Persistence
- **SQLite database** with volume mounting
- **Export capabilities**: JSON and CSV formats
- **Search functionality**: Full-text search across webhook payloads
- **Replay system**: Resend any webhook to any URL

### Modern UI/UX
- **Real-time updates** with HTMX and Server-Sent Events
- **Dark/light mode** with system preference detection
- **Responsive design** optimized for mobile and desktop
- **Syntax highlighting** for JSON payloads with Prism.js

---

## Platform Features

This template is optimized for modern cloud platforms:

- ✅ **One-click deployment** with railway.json template
- ✅ **Environment variable management** for configuration
- ✅ **Automatic persistent storage** via Railway volumes
- ✅ **Health checks** for service monitoring
- ✅ **Internal networking** for multi-service communication
- ✅ **Production security** with admin token protection
- ✅ **Modern web stack** (FastAPI + HTMX + TailwindCSS)
- ✅ **Cross-platform compatibility** (Unix/Windows/PowerShell)

---

## License

MIT License - Use freely for personal and commercial projects.
