hero/proxies/http/README.md

Hero HTTP Proxy

HTTP proxy server for converting webhook requests to WebSocket JSON-RPC calls to the Hero WebSocket server.

Overview

This proxy server acts as a bridge between HTTP webhook endpoints (like Stripe, iDenfy) and the Hero WebSocket server. It receives HTTP webhook requests, verifies signatures, and forwards them as JSON-RPC calls to the WebSocket server.

Features

• Webhook Support: Built-in support for Stripe and iDenfy webhooks
• Signature Verification: HMAC-SHA256 signature verification for security
• Extensible Design: Easy to add new webhook providers
• WebSocket Connection Pooling: Reuses WebSocket connections for efficiency
• Configurable: JSON-based configuration with environment variable support
• Health Checks: Built-in health check endpoint

Configuration

The proxy can be configured via a JSON configuration file or environment variables:

Environment Variables

• STRIPE_WEBHOOK_SECRET: Stripe webhook signing secret
• IDENFY_WEBHOOK_SECRET: iDenfy webhook signing secret

Configuration File Example

{
  "webhooks": {
    "stripe": {
      "secret": "whsec_...",
      "signature_header": "stripe-signature",
      "verify_signature": true
    },
    "idenfy": {
      "secret": "your_idenfy_secret",
      "signature_header": "idenfy-signature",
      "verify_signature": true
    }
  },
  "websocket_timeout": 30,
  "max_retries": 3
}

Usage

Basic Usage

cargo run -- --port 8080 --websocket-url ws://localhost:3030

With Configuration File

cargo run -- --port 8080 --websocket-url ws://localhost:3030 --config config.json

Command Line Options

• --port, -p: HTTP server port (default: 8080)
• --websocket-url, -w: WebSocket server URL (default: ws://localhost:3030)
• --config, -c: Configuration file path (optional)

Endpoints

Webhook Endpoints

• POST /webhooks/stripe/{circle_pk}: Stripe webhook handler
• POST /webhooks/idenfy/{circle_pk}: iDenfy webhook handler

Health Check

• GET /health: Health check endpoint

Adding New Webhook Providers

To add a new webhook provider:

1. Add configuration in src/config.rs:

   webhooks.insert("newprovider".to_string(), WebhookConfig {
       secret: std::env::var("NEWPROVIDER_WEBHOOK_SECRET").unwrap_or_default(),
       signature_header: "newprovider-signature".to_string(),
       verify_signature: true,
   });
   

2. Add signature verification in src/webhook/signature.rs:

   pub fn verify_newprovider_signature(
       payload: &[u8],
       signature_header: &str,
       secret: &str,
   ) -> Result<(), ProxyError> {
       // Implementation specific to the provider
   }
   

3. Add handler in src/webhook/handlers.rs:

   pub async fn handle_newprovider_webhook(
       req: HttpRequest,
       path: web::Path<String>,
       body: Bytes,
       data: web::Data<Arc<ProxyState>>,
   ) -> ActixResult<HttpResponse> {
       // Handler implementation
   }
   

4. Register route in src/main.rs:

   .route("/newprovider/{circle_pk}", web::post().to(webhook::handlers::handle_newprovider_webhook))
   

Architecture

HTTP Webhook → Signature Verification → JSON-RPC → WebSocket Server
     ↓                    ↓                ↓              ↓
  Stripe/iDenfy    HMAC-SHA256 Check    play method    Hero Server

The proxy maintains persistent WebSocket connections to the Hero server and forwards webhook events as play method calls with appropriate scripts (e.g., stripe_webhook_received, idenfy_webhook_received).

Dependencies

• actix-web: HTTP server framework
• tokio-tungstenite: WebSocket client
• heromodels: Hero project models (local dependency)
• serde: JSON serialization
• hmac/sha2: Signature verification
• clap: Command line argument parsing

Development

# Build
cargo build

# Run tests
cargo test

# Run with debug logging
RUST_LOG=debug cargo run

# Format code
cargo fmt

# Check for issues
cargo clippy