Autenticação e Headers

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.

Visão Geral dos Headers Customizados

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

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 subscrição via interface, você pode adicionar headers customizados que serão enviados automaticamente em todas as notificações:

Abra as configurações

Acesse as configurações do app no Workstation

Navegue até Events

Acesse a aba “Events”

Configure headers

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

Salve

Pronto! Todos os webhooks incluirão 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...}

Note como x-tela-forward-authorization se torna 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 suas próprias credenciais!

Melhores Práticas de Segurança

Apenas HTTPS

Sempre use URLs HTTPS - protegemos seus dados em trânsito

Autenticação Forte

Use Bearer tokens ou API keys em headers customizados

Valide Origem

Sempre valide que o webhook veio do 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 seu sistema requeira: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

Guias

Apps

Configurações

Recursos

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