Tunnel: Internal Data Flow Over the Internet

Overview

Tunnel allows incoming traffic from services outside of our AWS private network to access that network, generally in order to communicate with some other service that runs in ECS and isn't accessible over the internet itself.

An example use case for this is Stripe. We need to process Stripe events in the Wallstreet service, but don't want to expose Wallstreet to the internet via HTTP just so it can acknowledge webhooks. Besides, maybe another service beyond Wallstreet is interested in those same Stripe events.

API

Tunnel exposes HTTP webhook endpoints at tnl.pivot.app/ for receiving events from external services (Stripe, Mux, LiveKit, etc.). Each webhook route validates the incoming request signature and converts the payload to a NATS message for asynchronous processing by the appropriate internal service.

Tunnel also provides an HTTP API for PivotAdmin using the Connect protocol. Authentication for admin routes uses a two-layer approach: ALB source IP verification (PivotAdmin VPC CIDR) and request signature verification using a public/private key pair where the private key exists only in the PivotAdmin AWS account.

For the complete list of webhook routes and their NATS message schemas, refer to the proto definitions at proto/tunnel/tunnel/nats/v1/ in the pivot repository.

Databases

N/A

NATS

Publication

• tunnel.incoming_webhook_events.* - for Stripe, Mux, LiveKit events. (.stripe, .mux, .livekit)

Consumption

N/A

Temporal Workflows

N/A

Deployment

Security

• Rate limiting at the firewall level.