> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Common Route Patterns
> Real-world route examples and patterns. Learn from production-ready configurations for webhooks, APIs, payments, and more.
# 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:**
```json theme={"dark"}
Route: stripe-payments
Target: https://api.stripe.com
Methods: POST
```
**Headers:**
```json theme={"dark"}
{
"Authorization": "Bearer {{secret:stripe_prod_key}}",
"Content-Type": "application/json",
"Stripe-Version": "2023-10-16"
}
```
**Environment overrides:**
```text theme={"dark"}
Production:
Secret: stripe_prod_key (sk_live_...)
Staging:
Secret: stripe_staging_key (sk_test_...)
```
**Client request:**
```bash theme={"dark"}
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:**
```json theme={"dark"}
Route: paypal-checkout
Target: https://api.paypal.com
Methods: POST, GET
```
**Headers:**
```json theme={"dark"}
{
"Authorization": "Bearer {{secret:paypal_access_token}}",
"Content-Type": "application/json"
}
```
**OAuth2 Secret:**
```text theme={"dark"}
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:**
```json theme={"dark"}
Route: sendgrid-email
Target: https://api.sendgrid.com
Methods: POST
```
**Headers:**
```json theme={"dark"}
{
"Authorization": "Bearer {{secret:sendgrid_api_key}}",
"Content-Type": "application/json"
}
```
**Body template:**
```json theme={"dark"}
{
"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:**
```bash theme={"dark"}
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:**
```json theme={"dark"}
Route: mailgun-email
Target: https://api.mailgun.net
Methods: POST
```
**Headers:**
```json theme={"dark"}
{
"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:**
```json theme={"dark"}
Route: twilio-sms
Target: https://api.twilio.com
Methods: POST
```
**Headers:**
```json theme={"dark"}
{
"Authorization": "Basic {{secret:twilio_auth_token}}",
"Content-Type": "application/x-www-form-urlencoded"
}
```
**Secret format:**
```text theme={"dark"}
base64(ACCOUNT_SID:AUTH_TOKEN)
```
**Client request:**
```bash theme={"dark"}
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:**
```json theme={"dark"}
Route: stripe-webhooks
Target: https://your-backend.com
Methods: POST
```
**Headers:**
```json theme={"dark"}
{
"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:**
```text theme={"dark"}
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:**
```text theme={"dark"}
Option 1: Validate in your backend
Option 2: Use KnoxCall request signing
```
**Stripe configures webhook:**
```text theme={"dark"}
Webhook URL: https://YOUR-SUBDOMAIN.knoxcall.com/webhooks/stripe
```
***
### Receiving Shopify Webhooks
**Use case:** E-commerce webhook notifications
**Configuration:**
```json theme={"dark"}
Route: shopify-webhooks
Target: https://your-backend.com
Methods: POST
```
**Headers:**
```json theme={"dark"}
{
"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:**
```text theme={"dark"}
Allow: Shopify webhook IPs
(Or use signature validation instead of IP whitelist)
```
***
### Sending Webhooks to Partners
**Use case:** Notify partner systems of events
**Configuration:**
```json theme={"dark"}
Route: partner-acme-webhook
Target: https://webhooks.acme.com
Methods: POST
```
**Headers:**
```json theme={"dark"}
{
"X-Webhook-Secret": "{{secret:partner_acme_webhook_secret}}",
"Content-Type": "application/json",
"X-Source": "YourCompany"
}
```
**Body:**
```json theme={"dark"}
{
"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:**
```json theme={"dark"}
Route: database-api
Target: https://your-db-api.com
Methods: GET, POST
```
**Headers:**
```json theme={"dark"}
{
"Authorization": "Bearer {{secret:database_api_token}}",
"Content-Type": "application/json"
}
```
**Example queries:**
```bash theme={"dark"}
# 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:**
```json theme={"dark"}
Route: graphql-api
Target: https://api.example.com/graphql
Methods: POST
```
**Headers:**
```json theme={"dark"}
{
"Authorization": "Bearer {{secret:graphql_api_token}}",
"Content-Type": "application/json"
}
```
**Client query:**
```bash theme={"dark"}
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:**
```json theme={"dark"}
Route: s3-signed-urls
Target: https://your-backend.com/s3/sign
Methods: POST
```
**Headers:**
```json theme={"dark"}
{
"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:**
```json theme={"dark"}
Route: gcs-upload
Target: https://storage.googleapis.com
Methods: POST, PUT
```
**Headers:**
```json theme={"dark"}
{
"Authorization": "Bearer {{secret:google_cloud_oauth_token}}",
"Content-Type": "application/octet-stream"
}
```
**OAuth2 Secret:**
```text theme={"dark"}
Type: OAuth2
Auto-refresh: Enabled
```
***
## Printing Services
### PrintNode Cloud Printing
**Use case:** Send print jobs to remote printers
**Configuration:**
```json theme={"dark"}
Route: printnode-print
Target: https://api.printnode.com
Methods: POST
```
**Headers:**
```json theme={"dark"}
{
"Authorization": "Basic {{secret:printnode_api_key}}",
"Content-Type": "application/json"
}
```
**Body:**
```json theme={"dark"}
{
"printerId": 123,
"title": "Receipt #12345",
"contentType": "pdf_uri",
"content": "https://yoursite.com/receipt.pdf",
"source": "Your POS System"
}
```
**Client request:**
```bash theme={"dark"}
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:**
```json theme={"dark"}
Route: auth0-login
Target: https://YOUR-DOMAIN.auth0.com
Methods: POST
```
**Headers:**
```json theme={"dark"}
{
"Content-Type": "application/json"
}
```
**Body:**
```json theme={"dark"}
{
"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:**
```json theme={"dark"}
Route: google-oauth-token
Target: https://oauth2.googleapis.com/token
Methods: POST
```
**Headers:**
```json theme={"dark"}
{
"Content-Type": "application/x-www-form-urlencoded"
}
```
**Body:**
```json theme={"dark"}
{
"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:**
```text theme={"dark"}
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:**
```json theme={"dark"}
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:**
```json theme={"dark"}
Route: hubspot-crm
Target: https://api.hubapi.com
Methods: GET, POST, PATCH
```
**Headers:**
```json theme={"dark"}
{
"Authorization": "Bearer {{secret:hubspot_access_token}}",
"Content-Type": "application/json"
}
```
**OAuth2 Secret:** Auto-refreshing HubSpot token
***
### Salesforce API
**Use case:** CRM integration
**Configuration:**
```json theme={"dark"}
Route: salesforce-api
Target: https://your-instance.salesforce.com
Methods: GET, POST, PATCH, DELETE
```
**Headers:**
```json theme={"dark"}
{
"Authorization": "Bearer {{secret:salesforce_access_token}}",
"Content-Type": "application/json"
}
```
***
### Slack Webhooks
**Use case:** Send notifications to Slack
**Configuration:**
```json theme={"dark"}
Route: slack-notifications
Target: https://hooks.slack.com
Methods: POST
```
**Body:**
```json theme={"dark"}
{
"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:**
```json theme={"dark"}
Route: mock-api
Target: https://jsonplaceholder.typicode.com
Methods: GET, POST, PUT, DELETE
```
**Headers:**
```json theme={"dark"}
{
"Content-Type": "application/json"
}
```
**Clients:**
```text theme={"dark"}
Type: Server
IP: 192.168.1.0/24 (office network)
Environment: development only
```
***
### Webhook Testing
**Use case:** Test webhooks with webhook.site
**Configuration:**
```json theme={"dark"}
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):**
```text theme={"dark"}
Target: https://api.production.com
Secret: prod_api_key
Clients: [prod-server-1, prod-server-2]
```
**Override (Staging):**
```text theme={"dark"}
Target: https://api.staging.com
Secret: staging_api_key
Clients: [staging-server, qa-team]
```
**Override (Development):**
```text theme={"dark"}
Target: http://localhost:3000
Secret: dev_api_key
Clients: [ALL developers]
```
**Usage:**
```bash theme={"dark"}
# 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:**
```text theme={"dark"}
Route 1: api-v1 (old key)
Route 2: api-v2 (new key)
```
**Migration process:**
1. Create api-v2 with new key
2. Update clients gradually to use api-v2
3. Monitor api-v1 traffic
4. When api-v1 traffic = 0, delete it
**Zero downtime!**
***
### Multi-Layer Security
**Route:** `sensitive-api`
**Security layers:**
1. **IP whitelist** - Only production servers
2. **API key** - KnoxCall authentication
3. **Request signing** - HMAC signatures
4. **Rate limiting** - 100 req/min
5. **Secret injection** - Backend API key
**Configuration:**
```json theme={"dark"}
Requires Clients: ✓
Require Signature: ✓
Rate Limit: 100/min
Headers: {
"Authorization": "Bearer {{secret:backend_api_key}}"
}
```
***
## Best Practices
### ✅ Do
1. **Use environment-specific secrets**
```
Production: stripe_prod_key
Staging: stripe_test_key
```
2. **Document route purpose**
```
Description: "Stripe payment processing - live transactions"
```
3. **Start simple, add complexity**
```
1. Basic route
2. Add secrets
3. Add rate limiting
4. Add signing
```
4. **Test in staging first**
```
Staging → Success → Deploy to production
```
5. **Use descriptive names**
```
✅ stripe-prod-payments
❌ route1
```
### ❌ Don't
1. **Don't hardcode secrets**
```
❌ "Authorization": "Bearer sk_live_abc123"
✅ "Authorization": "Bearer {{secret:stripe_key}}"
```
2. **Don't use production keys in dev**
```
❌ Development using prod Stripe key
✅ Development using test Stripe key
```
3. **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
Route basics and concepts
Step-by-step route creation
Secret injection in routes
Advanced route features
***
**Pro Tip:** Copy these examples as starting points, then customize for your specific needs. Test in staging before deploying to production!