Common Route Patterns

Production-ready examples of common route configurations. Copy, adapt, and deploy.

Payment APIs

Stripe Payment Processing

Use case: Process payments securely without exposing Stripe API key Configuration:

Route: stripe-payments
Target: https://api.stripe.com
Methods: POST

Headers:

{
  "Authorization": "Bearer {{secret:stripe_prod_key}}",
  "Content-Type": "application/json",
  "Stripe-Version": "2023-10-16"
}

Environment overrides:

Production:
  Secret: stripe_prod_key (sk_live_...)

Staging:
  Secret: stripe_staging_key (sk_test_...)

Client request:

curl -X POST https://YOUR-SUBDOMAIN.knoxcall.com/v1/charges \
  -H "x-knoxcall-route: stripe-payments" \
  -H "x-knoxcall-key: YOUR_KEY" \
  -d "amount=1000" \
  -d "currency=usd" \
  -d "source=tok_visa"

Why this works:

Client never sees Stripe key
Environment-specific keys (test/live)
Full Stripe API access through proxy

PayPal Payments

Use case: PayPal checkout integration Configuration:

Route: paypal-checkout
Target: https://api.paypal.com
Methods: POST, GET

Headers:

{
  "Authorization": "Bearer {{secret:paypal_access_token}}",
  "Content-Type": "application/json"
}

OAuth2 Secret:

Type: OAuth2
Name: paypal_access_token
Token URL: https://api.paypal.com/v1/oauth2/token
Client ID: {{from PayPal dashboard}}
Client Secret: {{from PayPal dashboard}}

Auto-refresh: ✅ KnoxCall refreshes token automatically

Email Services

SendGrid Transactional Email

Use case: Send emails without exposing SendGrid API key Configuration:

Route: sendgrid-email
Target: https://api.sendgrid.com
Methods: POST

Headers:

{
  "Authorization": "Bearer {{secret:sendgrid_api_key}}",
  "Content-Type": "application/json"
}

Body template:

{
  "personalizations": [{
    "to": [{"email": "{{var:to_email}}"}],
    "subject": "{{var:subject}}"
  }],
  "from": {
    "email": "noreply@yourdomain.com",
    "name": "Your App"
  },
  "content": [{
    "type": "text/html",
    "value": "{{var:email_body}}"
  }]
}

Client request:

curl -X POST "https://YOUR-SUBDOMAIN.knoxcall.com/v3/mail/send?to_email=customer@example.com&subject=Welcome!&email_body=%3Ch1%3EWelcome%20to%20our%20service!%3C/h1%3E" \
  -H "x-knoxcall-route: sendgrid-email" \
  -H "x-knoxcall-key: YOUR_KEY"

Dynamic placeholders in body and header templates use the {{var:NAME}} form, where NAME is read from the request’s query-string parameters. Pass these values as query params (as shown above), not in the request body.

Mailgun Email

Use case: Alternative email service Configuration:

Route: mailgun-email
Target: https://api.mailgun.net
Methods: POST

Headers:

{
  "Authorization": "Basic {{secret:mailgun_api_key}}",
  "Content-Type": "application/x-www-form-urlencoded"
}

Note: Mailgun uses Basic auth (base64 encode api:YOUR_KEY)

SMS/Communication

Twilio SMS

Use case: Send SMS messages Configuration:

Route: twilio-sms
Target: https://api.twilio.com
Methods: POST

Headers:

{
  "Authorization": "Basic {{secret:twilio_auth_token}}",
  "Content-Type": "application/x-www-form-urlencoded"
}

Secret format:

base64(ACCOUNT_SID:AUTH_TOKEN)

Client request:

curl -X POST https://YOUR-SUBDOMAIN.knoxcall.com/2010-04-01/Accounts/ACCT_ID/Messages.json \
  -H "x-knoxcall-route: twilio-sms" \
  -H "x-knoxcall-key: YOUR_KEY" \
  -d "To=+15555555555" \
  -d "From=+14155552671" \
  -d "Body=Hello from KnoxCall!"

Webhooks

Receiving Stripe Webhooks

Use case: Receive webhook events from Stripe Configuration:

Route: stripe-webhooks
Target: https://your-backend.com
Methods: POST

Headers:

{
  "Content-Type": "application/json"
}

There is no {{client_ip}} template helper. The proxy strips reverse-proxy headers such as X-Forwarded-For from the request before forwarding it upstream, so the client IP is not passed through to your backend.

Clients:

Type: Server
IPs: Stripe webhook IPs
- 3.18.12.63/32
- 3.130.192.231/32
- 13.235.14.237/32
- 13.235.122.149/32
... (get full list from Stripe docs)

Signature validation:

Option 1: Validate in your backend
Option 2: Use KnoxCall request signing

Stripe configures webhook:

Webhook URL: https://YOUR-SUBDOMAIN.knoxcall.com/webhooks/stripe

Receiving Shopify Webhooks

Use case: E-commerce webhook notifications Configuration:

Route: shopify-webhooks
Target: https://your-backend.com
Methods: POST

Headers:

{
  "Content-Type": "application/json"
}

There is no {{header:...}} template helper. Incoming request headers that aren’t KnoxCall- or proxy-specific (such as X-Shopify-Hmac-SHA256, X-Shopify-Topic, and X-Shopify-Shop-Domain) are forwarded to your upstream automatically — you don’t need to re-declare them here.

Clients:

Allow: Shopify webhook IPs
(Or use signature validation instead of IP whitelist)

Sending Webhooks to Partners

Use case: Notify partner systems of events Configuration:

Route: partner-acme-webhook
Target: https://webhooks.acme.com
Methods: POST

Headers:

{
  "X-Webhook-Secret": "{{secret:partner_acme_webhook_secret}}",
  "Content-Type": "application/json",
  "X-Source": "YourCompany"
}

Body:

{
  "event": "order.created",
  "timestamp": "{{var:timestamp}}",
  "data": {
    "order_id": "12345",
    "total": 99.99
  },
  "signature": "{{var:hmac_signature}}"
}

KnoxCall does not generate timestamps or HMAC signatures for you. Compute these values on the client and pass them as query-string parameters (?timestamp=...&hmac_signature=...); the {{var:NAME}} placeholders read directly from the request query string.

Database / Data APIs

PostgreSQL REST API

Use case: Query database through HTTP API Configuration:

Route: database-api
Target: https://your-db-api.com
Methods: GET, POST

Headers:

{
  "Authorization": "Bearer {{secret:database_api_token}}",
  "Content-Type": "application/json"
}

Example queries:

# Read
curl https://YOUR-SUBDOMAIN.knoxcall.com/users/123 \
  -H "x-knoxcall-route: database-api"

# Write
curl -X POST https://YOUR-SUBDOMAIN.knoxcall.com/users \
  -H "x-knoxcall-route: database-api" \
  -d '{"name": "John", "email": "john@example.com"}'

GraphQL API

Use case: GraphQL backend proxy Configuration:

Route: graphql-api
Target: https://api.example.com/graphql
Methods: POST

Headers:

{
  "Authorization": "Bearer {{secret:graphql_api_token}}",
  "Content-Type": "application/json"
}

Client query:

curl -X POST https://YOUR-SUBDOMAIN.knoxcall.com/graphql \
  -H "x-knoxcall-route: graphql-api" \
  -d '{
    "query": "{ users { id name email } }"
  }'

Cloud Storage

AWS S3 Signed URLs

Use case: Generate pre-signed URLs for S3 uploads Configuration:

Route: s3-signed-urls
Target: https://your-backend.com/s3/sign
Methods: POST

Headers:

{
  "X-AWS-Access-Key": "{{secret:aws_access_key}}",
  "X-AWS-Secret-Key": "{{secret:aws_secret_key}}"
}

Your backend:

Generates signed URL using AWS credentials
Returns URL to client
Client uploads directly to S3

Google Cloud Storage

Use case: Upload files to Google Cloud Configuration:

Route: gcs-upload
Target: https://storage.googleapis.com
Methods: POST, PUT

Headers:

{
  "Authorization": "Bearer {{secret:google_cloud_oauth_token}}",
  "Content-Type": "application/octet-stream"
}

OAuth2 Secret:

Type: OAuth2
Auto-refresh: Enabled

Printing Services

PrintNode Cloud Printing

Use case: Send print jobs to remote printers Configuration:

Route: printnode-print
Target: https://api.printnode.com
Methods: POST

Headers:

{
  "Authorization": "Basic {{secret:printnode_api_key}}",
  "Content-Type": "application/json"
}

Body:

{
  "printerId": 123,
  "title": "Receipt #12345",
  "contentType": "pdf_uri",
  "content": "https://yoursite.com/receipt.pdf",
  "source": "Your POS System"
}

Client request:

curl -X POST https://YOUR-SUBDOMAIN.knoxcall.com/printjobs \
  -H "x-knoxcall-route: printnode-print" \
  -d '{
    "printerId": 123,
    "title": "Receipt",
    "content": "https://example.com/receipt.pdf"
  }'

Authentication / OAuth

Auth0 Authentication

Use case: User authentication proxy Configuration:

Route: auth0-login
Target: https://YOUR-DOMAIN.auth0.com
Methods: POST

Headers:

{
  "Content-Type": "application/json"
}

Body:

{
  "client_id": "{{secret:auth0_client_id}}",
  "client_secret": "{{secret:auth0_client_secret}}",
  "audience": "https://your-api.com",
  "grant_type": "client_credentials"
}

Google OAuth Token Exchange

Use case: Exchange authorization code for tokens Configuration:

Route: google-oauth-token
Target: https://oauth2.googleapis.com/token
Methods: POST

Headers:

{
  "Content-Type": "application/x-www-form-urlencoded"
}

Body:

{
  "client_id": "{{secret:google_client_id}}",
  "client_secret": "{{secret:google_client_secret}}",
  "code": "{{var:auth_code}}",
  "grant_type": "authorization_code",
  "redirect_uri": "https://yourapp.com/callback"
}

Microservices Architecture

Service-to-Service Communication

Use case: Multiple internal services Routes:

user-service → https://users.internal.com
order-service → https://orders.internal.com
payment-service → https://payments.internal.com
notification-service → https://notifications.internal.com

Shared configuration:

Headers (all services):
{
  "X-Internal-Token": "{{secret:internal_service_token}}",
  "X-Service-Name": "api-gateway"
}

Clients:
- Type: Server
- IP: 10.0.0.0/16 (internal VPC)

Benefits:

Centralized authentication
Unified logging
Rate limiting across services
Easy service discovery

Third-Party Integrations

HubSpot CRM

Use case: Sync customer data Configuration:

Route: hubspot-crm
Target: https://api.hubapi.com
Methods: GET, POST, PATCH

Headers:

{
  "Authorization": "Bearer {{secret:hubspot_access_token}}",
  "Content-Type": "application/json"
}

OAuth2 Secret: Auto-refreshing HubSpot token

Salesforce API

Use case: CRM integration Configuration:

Route: salesforce-api
Target: https://your-instance.salesforce.com
Methods: GET, POST, PATCH, DELETE

Headers:

{
  "Authorization": "Bearer {{secret:salesforce_access_token}}",
  "Content-Type": "application/json"
}

Slack Webhooks

Use case: Send notifications to Slack Configuration:

Route: slack-notifications
Target: https://hooks.slack.com
Methods: POST

Body:

{
  "text": "{{var:message}}",
  "channel": "#notifications",
  "username": "Your App Bot",
  "icon_emoji": ":robot_face:"
}

No auth needed (webhook URL is the secret)

Testing & Development

Mock API for Development

Use case: Test against mock data Configuration:

Route: mock-api
Target: https://jsonplaceholder.typicode.com
Methods: GET, POST, PUT, DELETE

Headers:

{
  "Content-Type": "application/json"
}

Clients:

Type: Server
IP: 192.168.1.0/24 (office network)
Environment: development only

Webhook Testing

Use case: Test webhooks with webhook.site Configuration:

Route: webhook-test
Target: https://webhook.site/YOUR-UNIQUE-ID
Methods: POST

Clients: Development team only

Multi-Environment Patterns

Pattern: Development → Staging → Production

Route: api-proxy Base (Production):

Target: https://api.production.com
Secret: prod_api_key
Clients: [prod-server-1, prod-server-2]

Override (Staging):

Target: https://api.staging.com
Secret: staging_api_key
Clients: [staging-server, qa-team]

Override (Development):

Target: http://localhost:3000
Secret: dev_api_key
Clients: [ALL developers]

Usage:

# Production
curl ... -H "x-knoxcall-environment: production"

# Staging
curl ... -H "x-knoxcall-environment: staging"

# Development
curl ... -H "x-knoxcall-environment: development"

Security Patterns

API Key Rotation Without Downtime

Setup two routes:

Route 1: api-v1 (old key)
Route 2: api-v2 (new key)

Migration process:

Create api-v2 with new key
Update clients gradually to use api-v2
Monitor api-v1 traffic
When api-v1 traffic = 0, delete it

Zero downtime!

Multi-Layer Security

Route: sensitive-api Security layers:

IP whitelist - Only production servers
API key - KnoxCall authentication
Request signing - HMAC signatures
Rate limiting - 100 req/min
Secret injection - Backend API key

Configuration:

Requires Clients: ✓
Require Signature: ✓
Rate Limit: 100/min
Headers: {
  "Authorization": "Bearer {{secret:backend_api_key}}"
}

Best Practices

✅ Do

Use environment-specific secrets

Production: stripe_prod_key
Staging: stripe_test_key

Document route purpose

Description: "Stripe payment processing - live transactions"

Start simple, add complexity

Basic route
Add secrets
Add rate limiting
Add signing

Test in staging first

Staging → Success → Deploy to production

Use descriptive names
✅ stripe-prod-payments ❌ route1

❌ Don’t

Don’t hardcode secrets

❌ "Authorization": "Bearer sk_live_abc123"
✅ "Authorization": "Bearer {{secret:stripe_key}}"

Don’t use production keys in dev

❌ Development using prod Stripe key
✅ Development using test Stripe key

Don’t skip IP authorization for prod

❌ Production route: requires_clients = false
✅ Production route: requires_clients = true

Quick Reference

Use Case	Target	Auth Method	Key Feature
Stripe	api.stripe.com	Bearer token	Secret injection
SendGrid	api.sendgrid.com	Bearer token	Email templates
Twilio	api.twilio.com	Basic auth	SMS/Voice
Webhooks	your-backend.com	IP + signature	Event notifications
PrintNode	api.printnode.com	Basic auth	Cloud printing
OAuth	oauth provider	Client credentials	Token exchange
Microservices	internal services	Internal token	Service mesh

Next Steps

What are Routes?

Route basics and concepts

Creating Routes

Step-by-step route creation

Using Secrets

Secret injection in routes

Advanced Configuration

Advanced route features

Pro Tip: Copy these examples as starting points, then customize for your specific needs. Test in staging before deploying to production!

​Common Route Patterns

​Payment APIs

​Stripe Payment Processing

​PayPal Payments

​Email Services

​SendGrid Transactional Email

​Mailgun Email

​SMS/Communication

​Twilio SMS

​Webhooks

​Receiving Stripe Webhooks

​Receiving Shopify Webhooks

​Sending Webhooks to Partners

​Database / Data APIs

​PostgreSQL REST API

​GraphQL API

​Cloud Storage

​AWS S3 Signed URLs

​Google Cloud Storage

​Printing Services

​PrintNode Cloud Printing

​Authentication / OAuth

​Auth0 Authentication

​Google OAuth Token Exchange

​Microservices Architecture

​Service-to-Service Communication

​Third-Party Integrations

​HubSpot CRM

​Salesforce API

​Slack Webhooks

​Testing & Development

​Mock API for Development

​Webhook Testing

​Multi-Environment Patterns

​Pattern: Development → Staging → Production

​Security Patterns

​API Key Rotation Without Downtime

​Multi-Layer Security

​Best Practices

​✅ Do

​❌ Don’t

​Quick Reference

​Next Steps

What are Routes?

Creating Routes

Using Secrets

Advanced Configuration

Common Route Patterns

Payment APIs

Stripe Payment Processing

PayPal Payments

Email Services

SendGrid Transactional Email

Mailgun Email

SMS/Communication

Twilio SMS

Webhooks

Receiving Stripe Webhooks

Receiving Shopify Webhooks

Sending Webhooks to Partners

Database / Data APIs

PostgreSQL REST API

GraphQL API

Cloud Storage

AWS S3 Signed URLs

Google Cloud Storage

Printing Services

PrintNode Cloud Printing

Authentication / OAuth

Auth0 Authentication

Google OAuth Token Exchange

Microservices Architecture

Service-to-Service Communication

Third-Party Integrations

HubSpot CRM

Salesforce API

Slack Webhooks

Testing & Development

Mock API for Development

Webhook Testing

Multi-Environment Patterns

Pattern: Development → Staging → Production

Security Patterns

API Key Rotation Without Downtime

Multi-Layer Security

Best Practices

✅ Do

❌ Don’t

Quick Reference

Next Steps