Skip to main content

​
Creating Your First Route

Get your first webhook route up and running. A route forwards incoming requests from your clients to your backend API with added security and monitoring.

​
What is a Route?

A route is a forwarding configuration that tells KnoxCall where to send incoming requests. Think of it as a smart proxy that:
  • ✅ Validates API keys and IP addresses
  • ✅ Injects secrets (API keys, OAuth tokens) into requests
  • ✅ Logs all requests and responses
  • ✅ Applies rate limiting
  • ✅ Supports multiple environments (dev, staging, production)

​
How Routes Work

Here’s the request flow: 
Client Request
    ↓
    POST https://a1b2c3d4.DunderMifflin.knoxcall.com/webhooks/order
    Headers:
      x-knoxcall-route: shopify-orders
      x-knoxcall-key: tk_abc123...  (for API key auth)
      OR your IP is whitelisted (for IP-based auth)
    ↓
KnoxCall Route Selection:
    - Subdomain identifies your TENANT (a1b2c3d4.DunderMifflin)
    - x-knoxcall-route header selects the ROUTE ("shopify-orders")
    ↓
    Validates API key OR IP address ✓
    Checks client authorization ✓
    Injects secrets: {{secret:shopify_api_key}}
    ↓
Forwards to: https://api.yourbackend.com/webhooks/order
    ↓
Response → Back to client
Important:
  • Subdomain determines your tenant
  • x-knoxcall-route header determines which route to use
  • The URL path (/webhooks/order) is passed through to your backend unchanged

​
Create Your First Route

​
Step 1: Open Routes Page

  1. Navigate to Routes in the sidebar
  2. Click Add Route

​
Step 2: Configure Basic Settings

Route Name: 
my-first-route
Lowercase, use hyphens. This name is used in the x-knoxcall-route header to identify which route to use. Target Base URL: 
https://jsonplaceholder.typicode.com
Your backend API’s base URL. We’ll use a test API for this example. Base Environment: 
production
Default environment (already created for you)

​
Step 3: Security Settings (Optional for Now)

You can leave these as defaults:
  • Requires Clients: ON (IP whitelist required)
  • Require Signature: OFF
  • Rate Limiting: OFF
We’ll cover these in later guides.

​
Step 4: Save

Click Create Route - your route is now live!

​
Test Your Route

​
Prerequisites

You need:
  1. Your tenant subdomain (e.g., a1b2c3d4.DunderMifflin.knoxcall.com)
  2. An API key (create one in Settings → Tenant tab → API Keys)

​
Make a Request

Option 1: Using API Key Authentication 
curl -X GET "https://a1b2c3d4.DunderMifflin.knoxcall.com/posts/1" \
  -H "x-knoxcall-route: my-first-route" \
  -H "x-knoxcall-key: tk_abc123_xyz789..."
Option 2: Using IP-Based Authentication (if your IP is whitelisted) 
curl -X GET "https://a1b2c3d4.DunderMifflin.knoxcall.com/posts/1" \
  -H "x-knoxcall-route: my-first-route"
Required Headers:
  • x-knoxcall-route: The route name you created (REQUIRED)
  • x-knoxcall-key: Your API key (if not using IP-based auth)
URL Structure:
  • https://a1b2c3d4.DunderMifflin.knoxcall.com → Your unique tenant subdomain
  • /posts/1 → Path passed through to your backend
  • Subdomain identifies your tenant, header identifies your route

​
Expected Response

You should see JSON data from the test API: 
{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere...",
  "body": "quia et suscipit..."
}
This means your route is working! 🎉

​
Understanding URL Mapping

KnoxCall forwards the entire path to your backend:
Client RequestTarget Base URLForwarded To
/posts/1https://api.example.comhttps://api.example.com/posts/1
/api/v2/usershttps://backend.comhttps://backend.com/api/v2/users
/webhooks/stripe?id=123https://app.comhttps://app.com/webhooks/stripe?id=123
Query parameters are also passed through unchanged.

​
View Request Logs

  1. Navigate to Logs → API Logs
  2. Find your request
  3. Click to see full details:
    • Request headers and body
    • Response headers and body
    • Response time
    • Status code
    • Source IP and geo-location

​
Common Configuration Options

​
Inject Headers

Add custom headers to every request: 
{
  "X-API-Key": "{{secret:my_api_key}}",
  "X-Custom-Header": "my-value"
}
Use {{secret:name}} to inject encrypted secrets from your vault.

​
Inject Body Fields

Add fields to JSON request bodies: 
{
  "api_key": "{{secret:printnode_key}}",
  "metadata": {
    "source": "knoxcall"
  }
}

​
Method-Specific Configuration

Configure different headers per HTTP method:
  • POST requests: Inject write API key
  • GET requests: Inject read-only API key
  • DELETE requests: Require admin API key
This is configured in the Method Configs section.

​
Security: Client IP Authorization

By default, requires_clients: true means only whitelisted IP addresses can use this route. To allow your IP:
  1. Navigate to Clients
  2. Click Add Client
  3. Enter:
    • Name: “My Office”
    • Type: “server”
    • IP Address: Your IP (or CIDR range like 192.168.1.0/24)
  4. Save
  5. Go back to your route → Clients tab
  6. Assign the client to the “production” environment
Now requests from your IP will work! To disable IP authorization (for testing):
  • Edit your route
  • Toggle Requires Clients to OFF
  • Save
Disabling client IP authorization means anyone with your API key can call the route. Only do this for public routes.

​
Common Issues

​
”Route not found”

Check:
  • The x-knoxcall-route header value matches your route name exactly (case-sensitive)
  • The route is enabled (toggle in route list)
  • You’re using the correct tenant subdomain

​
”IP not authorized”

Fix:
  • Add your IP address as a client (see “Client IP Authorization” above)
  • Or disable requires_clients temporarily for testing

​
”Invalid API key”

Check:
  • You copied the full 77-character API key
  • The key hasn’t been deleted
  • You’re using the correct tenant subdomain

​
”502 Bad Gateway”

Causes:
  • Your target URL is unreachable from the internet
  • The backend server is down
  • DNS resolution failed for the target domain
Debug:
  • Test the target URL directly: curl https://your-backend.com/endpoint
  • Check your backend server logs
  • Verify the target URL in route settings

​
”Connection timeout”

Causes:
  • Your backend is slow to respond (> 30 seconds default timeout)
  • Network connectivity issues
  • Backend server overloaded
Fix:
  • Increase timeout in route settings
  • Optimize your backend response time
  • Check backend server resources

​
Next Steps

Now that you have a working route:

Add IP Security

Whitelist IP addresses with clients

Use Environments

Set up dev, staging, production

Inject Secrets

Add encrypted API keys to requests

Rate Limiting

Protect your backend from abuse

​
Advanced Topics

  • AI Route Setup: Let AI configure routes from code or cURL commands
  • Route Examples: Real-world patterns for Stripe, Twilio, etc.
  • Request Signing: HMAC-SHA256 signatures to prevent replay attacks
  • Workflow Automation: Trigger workflows on route events
  • Webhooks: Get notified of successes and failures

📊 Statistics

  • Level: beginner
  • Time: 5 minutes

🏷️ Tags

routes, quickstart, beginner, proxy