Skip to main content
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:
1

Abra as configurações

Acesse as configurações do app no Workstation
2

Navegue até Events

Acesse a aba “Events”
3

Configure headers

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

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

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 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"
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)"
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
⌘I