Credenciais, webhooks e integrações

Esta página orienta a configuração segura de integrações usadas por flows. Nenhuma credencial real deve aparecer em documentação, exemplos, commits ou tickets.

O domínio app.exemplo.com e todos os IDs usados abaixo são fictícios; substitua-os pelos dados do ambiente correto.

Tipos de credencial

Em Credenciais de workflow, crie um registro com nome que identifique sistema e ambiente, como ERP — homologação.

Tipo	Campos protegidos	Uso atual
httpBearer	Token	Node Requisição HTTP, como cabeçalho Bearer.
httpBasic	Usuário e senha	Node Requisição HTTP, como Basic Auth.
apiKey	Chave	Assinatura opcional do trigger webhook e credencial obrigatória do node de IA.

Os dados são criptografados no banco e não voltam para a interface. Ao editar, deixe o segredo vazio para preservar o valor existente. Uma credencial referenciada por draft ou versão publicada não pode ser excluída.

Vincular uma credencial ao node

1. Crie a credencial antes de editar o flow.
2. No node, escolha a credencial no slot apresentado.
3. Salve e valide o draft.
4. Teste a renderização; o modo de teste não faz chamada externa real.
5. Publique e acompanhe a primeira execução real.

Slots atuais:

• Webhook: signature, opcional, aceita apiKey.
• Requisição HTTP: credential, opcional, aceita Bearer ou Basic.
• Requisição de IA: api, obrigatória, aceita apiKey.

Não coloque segredo em URL, query string, cabeçalho digitado, corpo Twig ou variável do flow. Esses campos podem aparecer em histórico e suporte.

Receber um webhook de flow

Depois de publicar, copie a URL exibida em Triggers publicados. Envie POST, JSON e uma chave única:

curl -X POST 'https://app.exemplo.com/workflow-hooks/CHAVE_PUBLICADA' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <ID_DO_EVENTO>' \
  -d '{"project_id":42,"status":"approved"}'

Uma entrega aceita retorna HTTP 202, executionId e status inicial. A mesma Idempotency-Key no mesmo trigger devolve a execução existente e não cria outra. Gere a chave a partir do ID imutável do evento no sistema de origem.

Assinatura opcional

Vincule uma credencial apiKey ao slot Assinatura do webhook. O emissor deve calcular HMAC SHA-256 sobre:

TIMESTAMP.CORPO_BRUTO

e enviar:

X-FlowOps-Timestamp: <unix timestamp>
X-FlowOps-Signature: sha256=<assinatura hexadecimal>

O timestamp precisa estar dentro de cinco minutos. Corpo, ordem de bytes e encoding usados no HMAC devem ser exatamente os enviados. Nunca inclua a chave no request.

Retomar um flow por callback

O node Aguardar webhook recebe um token renderizado com no mínimo 32 caracteres. O SteerCrew guarda somente o hash. O sistema externo deve manter o token temporariamente e chamar:

curl -X POST 'https://app.exemplo.com/workflow-callbacks/resume' \
  -H 'Authorization: Bearer <TOKEN_DE_RETOMADA>' \
  -H 'Content-Type: application/json' \
  -d '{"result":"approved"}'

A primeira chamada válida retoma a espera e normalmente retorna 202. Repetições depois do consumo não executam o ramo novamente. Use token aleatório, de uso único, não derivado de CPF, e-mail ou outro dado previsível.

Fazer chamadas HTTP externas

No node Requisição HTTP:

1. Escolha método e URL absoluta.
2. Use query, cabeçalhos e corpo apenas para dados não secretos.
3. Vincule Bearer ou Basic quando houver autenticação.
4. Defina timeout entre 1 e 60 segundos.
5. Escolha corpo sem conteúdo, JSON, formulário URL-encoded ou texto bruto.
6. Configure a política de erro e, se necessário, conecte a porta error.

O sistema adiciona Idempotency-Key por execução do node, não segue redirects, limita o tamanho da resposta e bloqueia localhost, redes privadas, endereços reservados e URLs com usuário/senha embutidos. Chamadas autenticadas exigem HTTPS.

Consequências práticas:

• a API de destino deve aceitar repetição idempotente;
• não use uma URL interna como http://10.0.0.5;
• a URL final precisa ser chamada diretamente, sem depender de redirecionamento;
• status HTTP de falha segue a política de erro do node;
• cabeçalhos e respostas conhecidos como sensíveis são ocultados no histórico.

Integrar um provedor de IA

1. Crie uma credencial apiKey.
2. Adicione Requisição de IA.
3. Informe a URL base HTTPS de uma API compatível com Chat Completions.
4. Informe modelo, prompt/mensagens e parâmetros opcionais.
5. Vincule a credencial ao slot api.
6. Teste o encadeamento em modo simulado e depois valide uma execução real controlada.

O sistema chama BASE_URL/chat/completions, sem redirects, com timeout de 60 segundos. A saída pode conter conteúdo e metadados do provedor; aplique minimização de dados e retenção compatível com o contrato do cliente.

Rotação e ambientes

• Use credenciais separadas para desenvolvimento, homologação e produção.
• Inclua o ambiente no nome, nunca no valor secreto.
• Para rotacionar, atualize o registro protegido e execute um teste real controlado.
• Revogue o segredo antigo no provedor depois da validação.
• Reavalie flows publicados que usam a credencial.
• Registre responsável e data de rotação fora do campo secreto.

Respostas e diagnóstico

Resposta/sintoma	Significado provável
401 no callback	Bearer ausente.
403 no webhook assinado	Credencial, timestamp ou assinatura inválida.
404 no trigger	Chave inexistente, trigger inativo ou versão não publicada.
413	Payload ou resposta acima do limite configurado.
422 no webhook	Idempotency-Key ausente.
OUTBOUND_ADDRESS_BLOCKED	URL resolveu para rede privada/reservada.
OUTBOUND_HTTPS_REQUIRED	Credencial vinculada a URL sem HTTPS.
HTTP_REQUEST_FAILED	API externa respondeu com erro.
HTTP_RESPONSE_TOO_LARGE	Resposta excedeu a retenção permitida.

Ao escalar, informe ambiente, flow, versão, ID da execução, node, horário, status HTTP e código técnico. Não envie credenciais nem corpo com dados pessoais sem canal aprovado.

Checklist de segurança

• [ ] Segredo salvo somente em credencial ou variável protegida do ambiente.
• [ ] HTTPS usado em produção.
• [ ] Webhook usa idempotência e, quando necessário, assinatura.
• [ ] Callback usa token aleatório de uso único.
• [ ] Destino externo não depende de redirect nem rede privada.
• [ ] Política de erro está explícita e testada.
• [ ] Payload contém somente os dados necessários.
• [ ] Rotação e revogação têm responsável definido.