Skip to main content
Security is fundamental in integrations. That’s why we offer full control over headers sent in webhooks, supporting any authentication method your system uses.

​
Custom Headers Overview

Workstation supports two types of custom headers, each optimized for different scenarios:

Fixed Headers

Configured once in the interface, automatically sent with each notification

Dynamic Headers

Passed per request via API, maximum flexibility for multi-tenant scenarios

​
Fixed Headers - For Permanent Configurations

Configure once, works forever When creating a subscription via the interface, you can add custom headers that will be automatically sent in all notifications:
1

Open settings

Access the app settings in Workstation
2

Navigate to Events

Access the “Events” tab
3

Configure headers

Add or edit a webhook and in the headers table, add your key-value pairs
4

Save

Done! All webhooks will include these headers

​
Use For

  • 🔐 Static authentication tokens (Bearer tokens, API keys)
  • 🏷️ Environment identifiers (staging, production)
  • 📋 Fixed integration metadata
  • 🔑 Any header that doesn’t change between requests

​
Example

Interface Configuration: 
Headers:
  authorization: Bearer fixed-company-token
  my-client-id: tela-production
  my-environment: prod
Each webhook will include: 
POST https://your-endpoint.com/webhook
authorization: Bearer fixed-company-token
my-client-id: tela-production
my-environment: prod
Content-Type: application/json

{...payload...}

​
Dynamic Headers - Maximum Flexibility

Full control per request For integrations that need maximum flexibility, pass different headers in each call using the x-tela-forward-* prefix:

​
How It Works

Any header you send with the x-tela-forward- prefix will be forwarded to your webhook endpoint without the prefix: 
POST /api/v1/tasks
Content-Type: application/json
x-tela-forward-authorization: Bearer token123
x-tela-forward-my-client-id: request-xyz
x-tela-forward-my-environment: production

{
  "webhook_url": "https://example.com/webhook",
  // ... other task data
}
The webhook will receive: 
POST https://example.com/webhook
authorization: Bearer token123
my-client-id: request-xyz
my-environment: production
Content-Type: application/json

{...payload...}
Note how x-tela-forward-authorization becomes just authorization in the webhook!

​
Perfect For

  • 🎯 Dynamic tokens that change per client
  • 🔗 Unique correlation IDs per request
  • 👤 User/session specific contexts
  • 🏢 Multi-tenant SaaS with per-client credentials

​
Multi-Tenant Example

# Client A Request
curl -X POST https://api.tela.com/v1/tasks \
  -H "x-tela-forward-authorization: Bearer client-a-token" \
  -H "x-tela-forward-tenant-id: client-a" \
  -d '{
    "webhook_url": "https://client-a.example.com/webhook",
    "prompt": "Process document"
  }'

# Client B Request
curl -X POST https://api.tela.com/v1/tasks \
  -H "x-tela-forward-authorization: Bearer client-b-token" \
  -H "x-tela-forward-tenant-id: client-b" \
  -d '{
    "webhook_url": "https://client-b.example.com/webhook",
    "prompt": "Process document"
  }'
Each client receives webhooks with their own credentials!

​
Security Best Practices

HTTPS Only

Always use HTTPS URLs - we protect your data in transit

Strong Authentication

Use Bearer tokens or API keys in custom headers

Validate Origin

Always validate that the webhook came from Workstation

Rotate Tokens

Regularly rotate your authentication tokens

​
Validation Example

// Validate webhook signature (example)
function validateWebhook(req) {
  const providedToken = req.headers['authorization'];
  const expectedToken = process.env.TELA_WEBHOOK_TOKEN;

  if (providedToken !== expectedToken) {
    throw new Error('Unauthorized webhook request');
  }
}

​
Common Authentication Methods

Most common method for API authentication:Fixed (interface configuration):
authorization: Bearer your-secret-token
Dynamic (per request):
-H "x-tela-forward-authorization: Bearer client-specific-token"
Simple API key in custom header:Fixed (interface configuration):
x-api-key: your-api-key-here
Dynamic (per request):
-H "x-tela-forward-x-api-key: client-api-key"
HTTP Basic authentication:Fixed (interface configuration):
authorization: Basic base64(username:password)
Dynamic (per request):
-H "x-tela-forward-authorization: Basic $(echo -n 'user:pass' | base64)"
Any custom authentication your system requires:Fixed (interface configuration):
x-custom-auth: your-value
x-secret-key: secret-123
Dynamic (per request):
-H "x-tela-forward-x-custom-auth: dynamic-value"
-H "x-tela-forward-x-secret-key: dynamic-secret"

​
Next Steps

Payload Reference

Understand webhook payloads
⌘I