Webhook Deployment

Standalone Webhook Server

pixcli includes a dedicated webhook server binary (pix-webhook-server) for production use. It handles mTLS, event forwarding, and logging.

Docker

FROM rust:1.75-slim as builder
RUN apt-get update && apt-get install -y libssl-dev pkg-config
WORKDIR /app
COPY . .
RUN cargo build --release -p pix-webhook-server

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/pix-webhook-server /usr/local/bin/
EXPOSE 8080
CMD ["pix-webhook-server", "--port", "8080"]

Build and run:

docker build -t pixcli-webhook .
docker run -d \
  -p 8080:8080 \
  -v /path/to/certs:/certs:ro \
  --name pixcli-webhook \
  pixcli-webhook

VPS with systemd

Create a systemd service file:

# /etc/systemd/system/pixcli-webhook.service
[Unit]
Description=pixcli Webhook Server
After=network.target

[Service]
Type=simple
User=pixcli
ExecStart=/usr/local/bin/pix-webhook-server \
  --port 8080 \
  --forward "https://hooks.slack.com/services/T00/B00/xxx" \
  --output /var/log/pixcli/events.jsonl
Restart=always
RestartSec=5
Environment=RUST_LOG=info

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable pixcli-webhook
sudo systemctl start pixcli-webhook
sudo systemctl status pixcli-webhook

Nginx Reverse Proxy with mTLS

For production Efí webhooks, configure nginx to handle mTLS:

server {
    listen 443 ssl;
    server_name webhook.example.com;

    # Your server certificate
    ssl_certificate /etc/ssl/certs/server.pem;
    ssl_certificate_key /etc/ssl/private/server.key;

    # Efí client certificate verification
    ssl_client_certificate /etc/ssl/certs/efi-ca.pem;
    ssl_verify_client on;

    location /webhook/pix {
        proxy_pass http://127.0.0.1:8080/pix;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Download Efí's CA certificate from the Efí developer portal.

ngrok (Development)

For local development without mTLS:

# Start webhook listener
pixcli webhook listen --port 8080

# In another terminal
ngrok http 8080

Then register the ngrok URL with --sandbox:

pixcli --sandbox webhook register \
  --key "+5511999999999" \
  --url "https://abc123.ngrok-free.app"

Cloudflare Tunnel

For a more permanent development setup:

cloudflared tunnel create pixcli-webhook
cloudflared tunnel route dns pixcli-webhook webhook.example.com
cloudflared tunnel run --url http://localhost:8080 pixcli-webhook

Railway / Fly.io / Render

The webhook server can be deployed to any container platform:

Fly.io

fly launch --image ghcr.io/pixcli/pix-webhook-server:latest
fly secrets set FORWARD_URL="https://hooks.slack.com/..."

Railway

Connect your GitHub repo and set the build command:

cargo build --release -p pix-webhook-server

For production deployments, always configure mTLS. Without it, anyone could send fake webhook events to your endpoint.

Webhook Deployment

On this page