Autenticação HTTP Webhook

Conecte a UiPath ao seu provedor de webhook e configure a verificação de desafio do webhook ou autenticação baseada em cabeçalho.

Pré-requisitos

Seu provedor de webhook pode exigir um handshake. Consulte a seção Verificação desafio do Webhook para obter detalhes sobre como configurar a verificação desafio.

Dependendo de onde você criar o gatilho, o URL do webhook gerado aparecerá na atividade HTTP Webhook Trigger ou na página de criação do gatilho, mas somente depois que a conexão for criada com sucesso. Para evitar falhas, cole o URL do webhook em seu aplicativo após publicar seu fluxo de trabalho ou o gatilho será criado com sucesso no UiPath Orchestrator.

Criação de uma conexão HTTP Webhook

1. Selecione Orchestrator no inicializador do produto.

2. Selecione uma pasta e navegue até a aba Conexões .

3. Selecione Adicionar conexão.

4. Para abrir a página de criação de conexão, selecione o conector na lista. Você pode usar a barra de pesquisa para encontrar o conector.

5. No campo Para qual aplicativo é esse webhook , insira um nome descritivo para o aplicativo de webhook, algo que facilita a identificação de qual fornecedor ou integração essa conexão representa. Esse valor se torna o Identificador de conexão.

6. (Opcional) Configure a autenticação baseada em cabeçalho.

   Se você quiser que a UiPath valide cada solicitação de webhook de entrada, no menu suspenso Tipo de autenticação , selecione Autenticação baseada em cabeçalho e especifique:

   • Chave de cabeçalho — o cabeçalho HTTP que o fornecedor usa para enviar a credencial (por exemplo, X-API-Key ou X-API-Secret).
   • Valor do cabeçalho — o valor do segredo que o fornecedor envia nesse cabeçalho (por exemplo, a1b2c3d4e5f6789...). Este campo é mascarado e armazenado com segurança. Você também pode usar um ativo de credencial para esse campo.

   Configure a mesma chave e valor de cabeçalho nas configurações do webhook do fornecedor. Se os valores não corresponderem no runtime, a UiPath rejeitará a solicitação com HTTP 401.

   Para obter mais informações, consulte Autenticação de cabeçalho do Webhook.

7. Configure o local do desafio
   Escolha como o fornecedor enviará o token de desafio para que a UiPath possa responder corretamente:

   • Sem desafio - o fornecedor não exige um handshake, e você pode prosseguir para a conexão.
   • Parâmetro de consulta (por exemplo, ?challenge=...)
   • Corpo JSON ( POST com { "challenge": "..." })
   • Cabeçalho (por exemplo, X-Hub-Challenge)

8. Configure a verificação de desafio e conecte-se
   Se o fornecedor exigir um handshake, insira a verificação de desafio que corresponde ao padrão do fornecedor (qual campo/cabeçalho/consulta ler e como repetir/validar). Quando a configuração for concluída, selecione Conectar.

   Quando disponível, selecione o menu ao lado de um campo e escolha Usar ativo de credencial ou Usar ativo do Orchestrator para fazer referência a um ativo do Orchestrator em vez de inserir o valor diretamente. Para obter mais informações, consulte Usar ativos de credenciais para conexões.

Dica:

• Use um nome que inclua o fornecedor e o ambiente (por exemplo, Stripe-prod ou Slack-staging) para evitar confusão.
• Se você não tiver certeza de qual padrão de desafio o fornecedor usa, verifique seus documentos do webhook ou execute um registro de teste para inspecionar a solicitação de handshake.

Verificação do desafio do Webhook

Alguns fornecedores exigem que os URLs do webhook sejam validados antes de começarem a enviar eventos reais. Isso é feito usando um mecanismo de desafio-resposta. Quando você registra um webhook, o fornecedor envia uma solicitação de desafio especial, e o ponto de extremidade deve responder exatamente conforme o esperado.

O conector HTTP Webhook é compatível com esses fluxos de verificação por meio do Framework de Desafios do Webhook, permitindo que você configure como a UiPath deve ler e responder aos desafios do fornecedor.

Suporte à verificação de desafio

A UiPath é compatível com ambos os tipos de comportamentos de webhook de fornecedor:

• Fornecedores que não usam a verificação de desafio
• Fornecedores que exigem um handshake antes de ativar o webhook

Isso garante compatibilidade com provedores de webhooks simples, bem como aqueles com requisitos de segurança mais avançados.

Quando os fornecedores não usam a verificação de desafio

Muitos aplicativos simplesmente aceitam um URL de webhook e começam a fornecer eventos imediatamente.
Para estes fornecedores:

• Os usuários só precisam criar ou selecionar uma conexão.
• Copie o URL do webhook.
• Cole-o na configuração do webhook do fornecedor.

Nenhuma etapa adicional é necessária. O webhook fica ativo assim que o fornecedor começa a enviar eventos.

Esse é o cenário mais comum e mais simples, e a UiPath lida com isso perfeitamente.

Quando os fornecedores exigem a verificação de desafio

Alguns fornecedores enviam uma solicitação de desafio para verificar o URL do webhook antes de habilitá-lo.
Nestes casos:

• Os usuários devem configurar a resposta do desafio na conexão HTTP do Webhook.
• A UiPath escuta a solicitação de desafio do fornecedor.
• A UiPath retorna automaticamente o valor de desafio correto com base na configuração.
• Depois que o fornecedor valida a resposta, os eventos normais começam a fluir.

Como os fornecedores diferem na forma como enviam o desafio (parâmetro de consulta, corpo JSON, cabeçalho etc.), a configuração da UiPath permite que os usuários lidem com qualquer um desses padrões.

Isso garante compatibilidade com provedores de webhook que impõem handshakes de segurança, como Slack, Meta (Facebook/Instagram), Stripe e outros.

Configurando a verificação de desafio

Você configura o comportamento desafio usando quatro parâmetros:

• Chave do Desafio
  Campo/chave que contém o valor do desafio. Usado para detectar solicitações de desafio (não deve ser nulo).

• Local do Desafio
  Onde a chave aparece:

  • Corpo
  • Parâmetro de consulta
  • Cabeçalho

• Tipo de conteúdo da resposta ao desafio
  Formato da resposta retornada ao fornecedor:

  • texto/simples
  • application/json

• Formato da Resposta do Desafio
  Define qual valor é retornado (em geral a própria chave de desafio).
  A UiPath extrai o valor do desafio que recebe e responde de acordo.

Exemplos de configuração de desafio

Exemplo genérico

Solicitação de entrada

 {
  "challenge": "ABC123"
 }

Configuração

• Chave do Desafio: challenge != null
• Local do desafio: corpo
• ResponseType: text/plain
• Formato da Resposta: challenge

Resposta

ABC123

Exemplo de verificação de desafio do WhatsApp

O WhatsApp usa o método de desafio baseado em parâmetro de consulta com hub.challenge.

Configuração

Parâmetro	Valor
Chave do Desafio	hub.challenge != null
Local do Desafio	Parâmetro de consulta
Tipo de conteúdo da resposta ao desafio	text/plain
Formato da Resposta do Desafio	hub.challenge

Solicitação do fornecedor

GET https://your-webhook-url?hub.challenge=1234567890

Resposta esperada da UiPath

HTTP/1.1 200 OK
Content-Type: text/plain

1234567890

Isso confirma a propriedade, e o WhatsApp começa a enviar eventos de webhook reais em seguida.

Resumo — Genérico vs WhatsApp

Etapa	Exemplo Genérico	Exemplo do WhatsApp
Local do Desafio	Corpo/Consulta/Cabeçalho	Consulta
FormatoDaChave	Chave simples (por exemplo, challenge)	Chave com ponto "hub.challenge")
ResponseType	texto/simples ou aplicativo/json	texto/simples
Valor da Resposta	Valor da chave	Valor de "hub.challenge"
Método	POST ou GET	Apenas GET

Exemplos por padrão de fornecedor

Exemplo 1: desafio de corpo simples com resposta de texto

Envios do fornecedor

{"challenge":"abc123","type":"url_verification"}

Campo	Valor
Local do desafio	Body
Chave do desafio	challenge
Tipo de conteúdo da resposta ao desafio	text
Formato de resposta ao desafio	challenge

Resposta: abc123 (texto/ simples, 200)

Exemplo 2: desafio do parâmetro de consulta com resposta de texto

Envios do fornecedor

GET /webhook?challenge=CHALLENGE_STRING

Campo	Valor
Local do desafio	Query Parameter
Chave do desafio	challenge
Tipo de conteúdo da resposta ao desafio	text
Formato de resposta ao desafio	challenge

Resposta: CHALLENGE_STRING (texto/ simples, 200)

Exemplo 3: desafio do corpo com resposta JSON

Envios do fornecedor

{"challenge":"abc123"}

Campo	Valor
Local do desafio	Body
Chave do desafio	challenge
Tipo de conteúdo da resposta ao desafio	json
Formato de resposta ao desafio	{ "challenge": "challenge" }

Resposta: {"challenge":"abc123"} (application/json, 200)

Exemplo 4: caminho de corpo aninhado (por exemplo, verification.token) com resposta de texto

Envios do fornecedor

{"verification":{"token":"abc123"}}

Campo	Valor
Local do desafio	Body
Chave do desafio	verification.token
Tipo de conteúdo da resposta ao desafio	text
Formato de resposta ao desafio	verification.token

Resposta: abc123 (texto/ simples, 200)

Exemplo 5: caminho profundamente aninhado com resposta JSON

Envios do fornecedor

{"event":{"challenge":"abc123","type":"verify"}}

Campo	Valor
Local do desafio	Body
Chave do desafio	event.challenge
Tipo de conteúdo da resposta ao desafio	json
Formato de resposta ao desafio	{ "result": "event.challenge" }

Resposta: {"result":"abc123"} (application/json, 200)

Exemplo 6: desafio baseado em cabeçalho (nome de cabeçalho com hifens) com resposta de texto

Envios do fornecedor

POST /webhook x-webhook-challenge: abc123

Campo	Valor
Local do desafio	Header
Chave do desafio	"x-webhook-challenge"
Tipo de conteúdo da resposta ao desafio	text
Formato de resposta ao desafio	"x-webhook-challenge"

Resposta: abc123 (texto/ simples, 200)

Observação:

O nome do cabeçalho contém hífens, que podem ser interpretados incorretamente como operadores em contextos de análise. Envolver o identificador em aspas duplas (por exemplo, "x-webhook-challenge") garante que ele seja tratado como um nome de chave literal. Sempre use aspas duplas ao redor de qualquer identificador que contenha hífens, pontos ou outros caracteres especiais.

Exemplo 7: detecção booleana com chave de resposta diferente

Envios do fornecedor

{"type":"url_verification","challenge":"abc","token":"legacytoken"}

Deseja detectar pelo campo type , mas responder com valor challenge .

Campo	Valor
Local do desafio	body
Chave do desafio	type == Verificação_url``
Tipo de conteúdo da resposta ao desafio	json
Formato de resposta ao desafio	{ "challenge": "challenge" }

Resposta: {"challenge":"abc"} (application/json, 200)

Autenticação de cabeçalho do webhook

A autenticação baseada em cabeçalho permite que a UiPath valide cada solicitação de webhook de entrada em relação a um segredo compartilhado que você configurou na criação da conexão. Isso impede que chamadores não autorizados disparem seus fluxos de trabalho publicando no seu URL do webhook.

Como funciona

Quando a autenticação baseada em cabeçalho é habilitada em uma conexão, o Integration Service:

1. Verifica cada solicitação de entrada para a chave de cabeçalho configurada.
2. Aceita o evento se o cabeçalho estiver presente e seu valor corresponder ao segredo armazenado.
3. Retorna HTTP 401 Não autorizado e não dispara nenhum fluxo de trabalho se o cabeçalho estiver ausente ou se seu valor não corresponder.

Exemplo de solicitação que a UiPath aceita:

POST /webhook HTTP/1.1
Host: <your-uipath-webhook-url>
X-API-Key: a1b2c3d4e5f6789...
Content-Type: application/json

{ "event": "..." }

Exemplo de solicitação que a UiPath rejeita (cabeçalho ausente ou valor incorreto):

HTTP/1.1 401 Unauthorized

Campos de configuração

A tabela a seguir descreve os campos que permitem que você configure a autenticação de cabeçalho do webhook na tela de criação da conexão.

Campo	Description	Exemplo
Tipo de Autenticação	Habilita ou desabilita a validação de cabeçalho para esta conexão.	Header Based Authentication / None
Chave do Cabeçalho	Nome do cabeçalho HTTP que o fornecedor envia.	X-API-Key, X-API-Secret
Valor do Cabeçalho	O valor do segredo que o fornecedor envia nesse cabeçalho. Mascarado em repouso.	a1b2c3d4e5f6789...

Compatibilidade do fornecedor

A autenticação baseada em cabeçalho funciona apenas com fornecedores que permitem que você configure um cabeçalho HTTP personalizado em entregas de webhook de saída.

Se você não tiver certeza se seu fornecedor é compatível com cabeçalhos personalizados de saída, consulte a documentação do webhook do fornecedor.

Atualização ou rotação do segredo

Quando você edita a conexão e altera o valor do cabeçalho, o novo valor entra em vigor imediatamente para todos os gatilhos que usam essa conexão. A configuração do fornecedor deve ser atualizada com o novo valor ao mesmo tempo, ou as entregas do fornecedor falharão com HTTP 401 até que você o faça.

Comportamento quando a autenticação falha

Uma solicitação será rejeitada com HTTP 401 Não autorizado se:

• O cabeçalho esperado está ausente da solicitação.
• O cabeçalho está presente, mas seu valor não corresponde ao segredo armazenado.

As solicitações com falha não são repetidas pelo UiPath, e nenhum evento de gatilho é enviado. O comportamento de nova tentativa do próprio fornecedor (se houver) se aplica.

Os rastreamentos de falha de autenticação podem ser visualizados na seção Traces . Para ajudar a proteger nossos sistemas contra ataques DoS, os rastreamentos de falha de autenticação são limitados a 5 por hora.

Observações importantes

• A autenticação baseada em cabeçalho tem o escopo de conexão. Todos os gatilhos criados para a mesma conexão compartilham a mesma chave e valor de cabeçalho — atualizar o segredo da conexão afeta todos os gatilhos que a utilizam.
• A autenticação baseada em cabeçalho é independente da verificação de desafio. Qualquer um, ambos ou nenhum pode ser habilitado em uma conexão.
• O valor do cabeçalho é armazenado criptografado e deve ser tratado com o mesmo cuidado que qualquer outra credencial.
• Os nomes dos cabeçalhos não diferenciam maiúsculas de minúsculas de acordo com a especificação HTTP (X-API-Key e x-api-key são equivalentes).