> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tela.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and Headers

> Secure your webhooks with custom headers

<Warning>Security is fundamental in integrations. That's why we offer **full control** over headers sent in webhooks, supporting any authentication method your system uses.</Warning>

## Custom Headers Overview

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

<CardGroup cols={2}>
  <Card title="Fixed Headers" icon="lock">
    Configured once in the interface, automatically sent with each notification
  </Card>

  <Card title="Dynamic Headers" icon="arrows-rotate">
    Passed per request via API, maximum flexibility for multi-tenant scenarios
  </Card>
</CardGroup>

## 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:

<Steps>
  <Step title="Open settings">
    Access the app settings in Workstation
  </Step>

  <Step title="Navigate to Events">
    Access the "Events" tab
  </Step>

  <Step title="Configure headers">
    Add or edit a webhook and in the headers table, add your key-value pairs
  </Step>

  <Step title="Save">
    Done! All webhooks will include these headers
  </Step>
</Steps>

### 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:**

```http theme={null}
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**:

```bash theme={null}
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:**

```http theme={null}
POST https://example.com/webhook
authorization: Bearer token123
my-client-id: request-xyz
my-environment: production
Content-Type: application/json

{...payload...}
```

<Info>Note how `x-tela-forward-authorization` becomes just `authorization` in the webhook!</Info>

### 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

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="HTTPS Only" icon="shield">
    Always use HTTPS URLs - we protect your data in transit
  </Card>

  <Card title="Strong Authentication" icon="key">
    Use Bearer tokens or API keys in custom headers
  </Card>

  <Card title="Validate Origin" icon="shield-check">
    Always validate that the webhook came from Workstation
  </Card>

  <Card title="Rotate Tokens" icon="arrows-rotate">
    Regularly rotate your authentication tokens
  </Card>
</CardGroup>

### Validation Example

```javascript theme={null}
// 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

<AccordionGroup>
  <Accordion title="Bearer Token" icon="key">
    Most common method for API authentication:

    **Fixed (interface configuration):**

    ```
    authorization: Bearer your-secret-token
    ```

    **Dynamic (per request):**

    ```bash theme={null}
    -H "x-tela-forward-authorization: Bearer client-specific-token"
    ```
  </Accordion>

  <Accordion title="API Key" icon="fingerprint">
    Simple API key in custom header:

    **Fixed (interface configuration):**

    ```
    x-api-key: your-api-key-here
    ```

    **Dynamic (per request):**

    ```bash theme={null}
    -H "x-tela-forward-x-api-key: client-api-key"
    ```
  </Accordion>

  <Accordion title="Basic Auth" icon="user-shield">
    HTTP Basic authentication:

    **Fixed (interface configuration):**

    ```
    authorization: Basic base64(username:password)
    ```

    **Dynamic (per request):**

    ```bash theme={null}
    -H "x-tela-forward-authorization: Basic $(echo -n 'user:pass' | base64)"
    ```
  </Accordion>

  <Accordion title="Custom Headers" icon="code">
    Any custom authentication your system requires:

    **Fixed (interface configuration):**

    ```
    x-custom-auth: your-value
    x-secret-key: secret-123
    ```

    **Dynamic (per request):**

    ```bash theme={null}
    -H "x-tela-forward-x-custom-auth: dynamic-value"
    -H "x-tela-forward-x-secret-key: dynamic-secret"
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={1}>
  <Card title="Payload Reference" icon="file-code" href="/en/workstation/events/payload-reference">
    Understand webhook payloads
  </Card>
</CardGroup>