Autenticação e headers

Segurança é fundamental em integrações. Por isso, você tem controle total sobre os headers enviados nos webhooks e pode usar qualquer método de autenticação que o seu sistema exija.

Visão Geral dos Headers Customizados

A Workstation aceita dois tipos de headers customizados, cada um pensado para um cenário:

Headers Fixos

Configurados uma vez na interface, enviados automaticamente com cada notificação

Headers Dinâmicos

Passados por requisição via API, máxima flexibilidade para cenários multi-tenant

Headers Fixos - Para Configurações Permanentes

Configure uma vez, funciona para sempre Ao criar uma assinatura pela interface, você pode adicionar headers customizados, enviados automaticamente em todas as notificações:

Abra as configurações

Acesse as configurações do app na Workstation

Navegue até Events

Acesse a aba “Events”

Configure headers

Adicione ou edite um webhook e, na tabela de headers, inclua os seus pares chave-valor

Salve

Pronto. Todos os webhooks passam a incluir esses headers

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

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:

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

POST https://exemplo.com/webhook
authorization: Bearer token123
my-client-id: request-xyz
my-environment: production
Content-Type: application/json

{...payload...}

Repare que x-tela-forward-authorization vira apenas authorization no webhook.

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

# 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 as próprias credenciais.

Melhores Práticas de Segurança

Apenas HTTPS

Sempre use URLs HTTPS para proteger os dados em trânsito

Autenticação Forte

Use Bearer tokens ou API keys em headers customizados

Valide Origem

Confirme sempre que o webhook veio da Workstation

Rotacione Tokens

Rotacione regularmente seus tokens de autenticação

Exemplo de Validação

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

Bearer Token

Método mais comum para autenticação de API:Fixo (configuração na interface):

authorization: Bearer seu-token-secreto

Dinâmico (por requisição):

-H "x-tela-forward-authorization: Bearer token-especifico-cliente"

API Key

API key simples em header customizado:Fixo (configuração na interface):

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

Dinâmico (por requisição):

-H "x-tela-forward-x-api-key: api-key-cliente"

Basic Auth

Autenticação HTTP Basic:Fixo (configuração na interface):

authorization: Basic base64(username:password)

Dinâmico (por requisição):

-H "x-tela-forward-authorization: Basic $(echo -n 'user:pass' | base64)"

Headers Customizados

Qualquer autenticação customizada que o seu sistema exija:Fixo (configuração na interface):

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

Dinâmico (por requisição):

-H "x-tela-forward-x-custom-auth: valor-dinamico"
-H "x-tela-forward-x-secret-key: secret-dinamico"

Próximos Passos

Referência de Payload

Entenda payloads de webhook

Primeiros passos

Construir

Testar

Operar

Integrar

Autenticação e headers

Visão Geral dos Headers Customizados

Headers Fixos

Headers Dinâmicos

Headers Fixos - Para Configurações Permanentes

Use Para

Exemplo

Headers Dinâmicos - Máxima Flexibilidade

Como Funciona

Perfeito Para

Exemplo Multi-Tenant

Melhores Práticas de Segurança

Apenas HTTPS

Autenticação Forte

Valide Origem

Rotacione Tokens

Exemplo de Validação

Métodos Comuns de Autenticação

Próximos Passos

Referência de Payload

​Visão Geral dos Headers Customizados

Headers Fixos

Headers Dinâmicos

​Headers Fixos - Para Configurações Permanentes

​Use Para

​Exemplo

​Headers Dinâmicos - Máxima Flexibilidade

​Como Funciona

​Perfeito Para

​Exemplo Multi-Tenant

​Melhores Práticas de Segurança

Apenas HTTPS

Autenticação Forte

Valide Origem

Rotacione Tokens

​Exemplo de Validação

​Métodos Comuns de Autenticação

​Próximos Passos

Referência de Payload

Visão Geral dos Headers Customizados

Headers Fixos - Para Configurações Permanentes

Use Para

Exemplo

Headers Dinâmicos - Máxima Flexibilidade

Como Funciona

Perfeito Para

Exemplo Multi-Tenant

Melhores Práticas de Segurança

Exemplo de Validação

Métodos Comuns de Autenticação

Próximos Passos