Use Case

You have multiple services that need webhooks, and NGINX already handles internal routing. Use Skooh + NGINX for clean separation:

• Skooh: External → Internal
• NGINX: Internal routing to services

Architecture

Internet → Skooh Cloud → Skooh Proxy → NGINX → Service A
                                           ↘ Service B
                                           ↘ Service C

Setup

1. Run the Skooh Proxy

Using the Desktop App:

1. Download the Skooh Desktop App
2. Enter your API key and hook token
3. Set forwarding URL to your NGINX (e.g., `http://localhost:80/webhooks\`)
4. Click Connect

Using Docker:

docker run -d \\
  --name skooh-proxy \\
  -e SKOOH_TOKEN=main-webhooks \\
  -e SKOOH_API_KEY=your_api_key \\
  -e FORWARD_URL=http://nginx:80/webhooks \\
  --network internal \\
  --restart unless-stopped \\
  skooh/proxy

2. NGINX Configuration

upstream payments_service {
    server payments:8080;
}

upstream orders_service {
    server orders:8080;
}

upstream notifications_service {
    server notifications:8080;
}

server {
    listen 80;
    server_name _;

    # Route by path
    location /webhooks/stripe {
        proxy_pass http://payments_service/webhooks/stripe;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /webhooks/shopify {
        proxy_pass http://orders_service/webhooks/shopify;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /webhooks/sendgrid {
        proxy_pass http://notifications_service/webhooks/sendgrid;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Catch-all for unmatched webhooks
    location /webhooks {
        return 404 "Unknown webhook path";
    }
}

3. Docker Compose

version: '3.8'

services:
  skooh-proxy:
    image: skooh/proxy
    environment:
      SKOOH_TOKEN: main-webhooks
      SKOOH_API_KEY: \${SKOOH_API_KEY}
      FORWARD_URL: http://nginx/webhooks
    depends_on:
      - nginx
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - payments
      - orders
      - notifications

  payments:
    image: your-org/payments:latest
    # ...

  orders:
    image: your-org/orders:latest
    # ...

  notifications:
    image: your-org/notifications:latest
    # ...

Preserving Headers

Ensure NGINX passes through webhook headers:

location /webhooks/stripe {
    proxy_pass http://payments_service/webhooks/stripe;
    
    # Pass all headers (important for signatures!)
    proxy_pass_request_headers on;
    
    # Preserve original headers
    proxy_set_header X-Original-Host $http_host;
    proxy_set_header X-Original-URI $request_uri;
}

Request Logging

Add logging for debugging:

log_format webhook_log '$remote_addr - $time_local '
                       '"$request" $status $body_bytes_sent '
                       '"$http_x_webhook_source" "$http_user_agent"';

server {
    access_log /var/log/nginx/webhooks.log webhook_log;
    # ...
}

Load Balancing

For high-traffic services:

upstream payments_service {
    least_conn;
    server payments-1:8080;
    server payments-2:8080;
    server payments-3:8080;
}

Health Checks

Add health check endpoint:

location /health {
    return 200 "OK";
    add_header Content-Type text/plain;
}

Configure NGINX routing →