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

# Autenticação e Headers

> Proteja seus webhooks com headers customizados

<Warning>Segurança é fundamental em integrações. Por isso, oferecemos **controle total** sobre os headers enviados nos webhooks, suportando qualquer método de autenticação que seu sistema utilize.</Warning>

## Visão Geral dos Headers Customizados

O Workstation suporta dois tipos de headers customizados, cada um otimizado para diferentes cenários:

<CardGroup cols={2}>
  <Card title="Headers Fixos" icon="lock">
    Configurados uma vez na interface, enviados automaticamente com cada notificação
  </Card>

  <Card title="Headers Dinâmicos" icon="arrows-rotate">
    Passados por requisição via API, máxima flexibilidade para cenários multi-tenant
  </Card>
</CardGroup>

## Headers Fixos - Para Configurações Permanentes

**Configure uma vez, funciona para sempre**

Ao criar uma subscrição via interface, você pode adicionar headers customizados que serão enviados automaticamente em todas as notificações:

<Steps>
  <Step title="Abra as configurações">
    Acesse as configurações do app no Workstation
  </Step>

  <Step title="Navegue até Events">
    Acesse a aba "Events"
  </Step>

  <Step title="Configure headers">
    Adicione ou edite um webhook e na tabela de headers, adicione seus pares chave-valor
  </Step>

  <Step title="Salve">
    Pronto! Todos os webhooks incluirão esses headers
  </Step>
</Steps>

### Use Para

* 🔐 Tokens de autenticação estáticos (Bearer tokens, API keys)
* 🏷️ Identificadores de ambiente (staging, production)
* 📋 Metadados fixos da sua integração
* 🔑 Qualquer header que não muda entre requisições

### Exemplo

**Configuração na Interface:**

```
Headers:
  authorization: Bearer token-fixo-empresa
  my-client-id: tela-production
  my-environment: prod
```

**Cada webhook incluirá:**

```http theme={null}
POST https://seu-endpoint.com/webhook
authorization: Bearer token-fixo-empresa
my-client-id: tela-production
my-environment: prod
Content-Type: application/json

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

## Headers Dinâmicos - Máxima Flexibilidade

**Controle total por requisição**

Para integrações que precisam de flexibilidade máxima, passe headers diferentes em cada chamada usando o prefixo `x-tela-forward-*`:

### Como Funciona

Qualquer header que você enviar com o prefixo `x-tela-forward-` será encaminhado para seu endpoint de webhook **sem o prefixo**:

```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://exemplo.com/webhook",
  // ... outros dados da task
}
```

**O webhook receberá:**

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

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

<Info>Note como `x-tela-forward-authorization` se torna apenas `authorization` no webhook!</Info>

### Perfeito Para

* 🎯 Tokens dinâmicos que mudam por cliente
* 🔗 IDs de correlação únicos por requisição
* 👤 Contextos específicos de usuário/sessão
* 🏢 SaaS multi-tenant com credenciais por cliente

### Exemplo Multi-Tenant

```bash theme={null}
# Requisição Cliente A
curl -X POST https://api.tela.com/v1/tasks \
  -H "x-tela-forward-authorization: Bearer token-cliente-a" \
  -H "x-tela-forward-tenant-id: cliente-a" \
  -d '{
    "webhook_url": "https://cliente-a.exemplo.com/webhook",
    "prompt": "Processar documento"
  }'

# Requisição Cliente B
curl -X POST https://api.tela.com/v1/tasks \
  -H "x-tela-forward-authorization: Bearer token-cliente-b" \
  -H "x-tela-forward-tenant-id: cliente-b" \
  -d '{
    "webhook_url": "https://cliente-b.exemplo.com/webhook",
    "prompt": "Processar documento"
  }'
```

Cada cliente recebe webhooks com suas próprias credenciais!

## Melhores Práticas de Segurança

<CardGroup cols={2}>
  <Card title="Apenas HTTPS" icon="shield">
    Sempre use URLs HTTPS - protegemos seus dados em trânsito
  </Card>

  <Card title="Autenticação Forte" icon="key">
    Use Bearer tokens ou API keys em headers customizados
  </Card>

  <Card title="Valide Origem" icon="shield-check">
    Sempre valide que o webhook veio do Workstation
  </Card>

  <Card title="Rotacione Tokens" icon="arrows-rotate">
    Rotacione regularmente seus tokens de autenticação
  </Card>
</CardGroup>

### Exemplo de Validação

```javascript theme={null}
// Validar assinatura do webhook (exemplo)
function validateWebhook(req) {
  const providedToken = req.headers['authorization'];
  const expectedToken = process.env.TELA_WEBHOOK_TOKEN;

  if (providedToken !== expectedToken) {
    throw new Error('Requisição de webhook não autorizada');
  }
}
```

## Métodos Comuns de Autenticação

<AccordionGroup>
  <Accordion title="Bearer Token" icon="key">
    Método mais comum para autenticação de API:

    **Fixo (configuração na interface):**

    ```
    authorization: Bearer seu-token-secreto
    ```

    **Dinâmico (por requisição):**

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

  <Accordion title="API Key" icon="fingerprint">
    API key simples em header customizado:

    **Fixo (configuração na interface):**

    ```
    x-api-key: sua-api-key-aqui
    ```

    **Dinâmico (por requisição):**

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

  <Accordion title="Basic Auth" icon="user-shield">
    Autenticação HTTP Basic:

    **Fixo (configuração na interface):**

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

    **Dinâmico (por requisição):**

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

  <Accordion title="Headers Customizados" icon="code">
    Qualquer autenticação customizada que seu sistema requeira:

    **Fixo (configuração na interface):**

    ```
    x-custom-auth: seu-valor
    x-secret-key: secret-123
    ```

    **Dinâmico (por requisição):**

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

## Próximos Passos

<CardGroup cols={1}>
  <Card title="Referência de Payload" icon="file-code" href="/pt/workstation/events/payload-reference">
    Entenda payloads de webhook
  </Card>
</CardGroup>