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

Navigate to Routes in the sidebar
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:

Your tenant subdomain (e.g., a1b2c3d4.DunderMifflin.knoxcall.com)
An API key (create one in Settings → 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 Request	Target Base URL	Forwarded To
`/posts/1`	`https://api.example.com`	`https://api.example.com/posts/1`
`/api/v2/users`	`https://backend.com`	`https://backend.com/api/v2/users`
`/webhooks/stripe?id=123`	`https://app.com`	`https://app.com/webhooks/stripe?id=123`

Query parameters are also passed through unchanged.

View Request Logs

Navigate to Logs → API Logs
Find your request
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:

Navigate to Clients
Click Add Client
Enter:
- Name: “My Office”
- Type: “server”
- IP Address: Your IP (or CIDR range like 192.168.1.0/24)
Save
Go back to your route → Environment Clients tab
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 72-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

Getting Started

Essentials: Routes

Essentials: Clients

Essentials: Secrets

Essentials: Environments

Webhooks

Workflows

Security

Monitoring

Advanced Features

Infrastructure

Account

Troubleshooting

Support

About

​Creating Your First Route

​What is a Route?

​How Routes Work

​Create Your First Route

​Step 1: Open Routes Page

​Step 2: Configure Basic Settings

​Step 3: Security Settings (Optional for Now)

​Step 4: Save

​Test Your Route

​Prerequisites

​Make a Request

​Expected Response

​Understanding URL Mapping

​View Request Logs

​Common Configuration Options

​Inject Headers

​Inject Body Fields

​Method-Specific Configuration

​Security: Client IP Authorization

​Common Issues

​”Route not found”

​”IP not authorized”

​”Invalid API key”

​”502 Bad Gateway”

​”Connection timeout”

​Next Steps

Add IP Security

Use Environments

Inject Secrets

Rate Limiting

​Advanced Topics

📊 Statistics

🏷️ Tags

Creating Your First Route

What is a Route?

How Routes Work

Create Your First Route

Step 1: Open Routes Page

Step 2: Configure Basic Settings

Step 3: Security Settings (Optional for Now)

Step 4: Save

Test Your Route

Prerequisites

Make a Request

Expected Response

Understanding URL Mapping

View Request Logs

Common Configuration Options

Inject Headers

Inject Body Fields

Method-Specific Configuration

Security: Client IP Authorization

Common Issues

”Route not found”

”IP not authorized”

”Invalid API key”

”502 Bad Gateway”

”Connection timeout”

Next Steps

Advanced Topics