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. (Optional) Configure header-based authentication.

   If you want UiPath to validate every incoming webhook request, from the Authentication Type dropdown select Header Based Authentication, then specify:

   • Header key — the HTTP header the vendor uses to send the credential (for example, X-API-Key or X-API-Secret).
   • Header value — the secret value the vendor sends in that header (for example, a1b2c3d4e5f6789...). This field is masked and stored securely. You can also use a credential asset for this field.

   Configure the same header key and value in the vendor's webhook settings. If the values don't match at runtime, UiPath rejects the request with HTTP 401.

   For more information, see Webhook header authentication.

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
   If the vendor requires a handshake, enter the challenge verification that matches the vendor's pattern (which field/header/query to read and how to echo/validate it). When configuration is complete, select Connect.

   Where available, select the menu next to a field and choose Use credential asset or Use Orchestrator asset to reference an Orchestrator asset instead of entering the value directly. For more information, see Use credential assets for connections.

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)

Webhook header authentication

Header-based authentication lets UiPath validate every incoming webhook request against a shared secret you configured at connection creation. This prevents unauthorized callers from triggering your workflows by posting to your webhook URL.

Como funciona

When header-based authentication is enabled on a connection, Integration Service:

1. Checks every incoming request for the configured header key.
2. Accepts the event if the header is present and its value matches the stored secret.
3. Returns HTTP 401 Unauthorized and does not trigger any workflow if the header is absent or its value does not match.

Example request that UiPath accepts:

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

{ "event": "..." }

Example request that UiPath rejects (header missing or value wrong):

HTTP/1.1 401 Unauthorized

Campos de configuração

The following table describes the fields that enable you to configure webhook header authentication on the connection creation screen.

Campo	Description	Exemplo
Tipo de Autenticação	Enables or disables header validation for this connection.	Header Based Authentication / None
Header Key	Name of the HTTP header the vendor sends.	X-API-Key, X-API-Secret
Header Value	Secret value the vendor sends in that header. Masked at rest.	a1b2c3d4e5f6789...

Vendor compatibility

Header-based authentication only works with vendors that let you configure a custom HTTP header on outbound webhook deliveries.

If you're unsure whether your vendor supports outbound custom headers, check the vendor's webhook documentation.

Updating or rotating the secret

When you edit the connection and change the header value, the new value takes effect immediately for all triggers using that connection. The vendor's configuration must be updated with the new value at the same time, or the vendor's deliveries will fail with HTTP 401 until you do.

Behavior when authentication fails

A request is rejected with HTTP 401 Unauthorized if:

• The expected header is absent from the request.
• The header is present but its value does not match the stored secret.

Failed requests are not retried by UiPath, and no trigger event is dispatched. The vendor's own retry behavior (if any) applies.

Authentication failure traces can be viewed in the Traces section. To help protect our systems from DoS attacks, authentication failure traces are limited to 5 per hour.

Observações importantes

• Header-based authentication is connection-scoped. All triggers created against the same connection share the same header key and value — updating the connection's secret affects every trigger using it.
• Header-based authentication is independent of challenge verification. Either, both, or neither can be enabled on a connection.
• The header value is stored encrypted and should be handled with the same care as any other credential.
• Header names are case-insensitive per the HTTP specification (X-API-Key and x-api-key are equivalent).