Autenticação HTTP Webhook

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. 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)
7. 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 fazê-lo/validar). Quando a configuração estiver concluída, clique em Conectar.

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

O fornecedor envia:

{"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

O fornecedor envia:

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

O fornecedor envia:

{"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

O fornecedor envia:

{"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

O fornecedor envia:

{"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

O fornecedor envia:

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

O fornecedor envia:

{"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)