UiPath Documentation
integration-service
latest
false
Guía de usuario de Integration Service
Importante :
Este contenido se ha traducido mediante traducción automática. Los paquetes de conectores disponibles en Integration Service están traducidos con traducción automática. La localización de contenidos recién publicados puede tardar entre una y dos semanas en estar disponible.

Autenticación HTTP Webhook

Connect UiPath to your webhook provider and configure webhook challenge verification, header-based authentication, or JWT authentication.

Requisitos previos​

Tu proveedor de webhook puede requerir un protocolo de enlace. Consulta la sección Verificación de desafío de Webhook para obtener más información sobre cómo configurar la verificación de desafío.

Dependiendo de dónde crees el desencadenador, la URL del webhook generado aparecerá en la actividad del desencadenador HTTP Webhook o en la página de creación del desencadenador, pero solo después de que la conexión se haya creado correctamente. Para evitar fallos, pegue la URL del webhook en su aplicación después de publicar su flujo de trabajo o el desencadenador se haya creado correctamente en UiPath Orchestrator.

Crear una conexión HTTP Webhook​

  1. Selecciona Orchestrator en el lanzador de productos.

  2. Selecciona una carpeta y luego navega a la pestaña Conexiones .

  3. Selecciona Añadir conexión.

  4. Para abrir la página de creación de conexiones, selecciona el conector de la lista. Puedes utilizar la barra de búsqueda para encontrar el conector.

  5. En el campo Para qué aplicación es este webhook , introduce un nombre descriptivo para la aplicación de webhook, algo que facilite la identificación de qué proveedor o integración representa esta conexión. Este valor se convierte en el Identificador de conexión.

  6. (Optional) Configure authentication.

    If you want UiPath to validate every incoming webhook request, select a method from the Authentication Type dropdown.

    For Header Based Authentication, specify:

    • Clave de encabezado : el encabezado HTTP que el proveedor utiliza para enviar la credencial (por ejemplo, X-API-Key o X-API-Secret).
    • Valor de encabezado : el valor secreto que el proveedor envía en ese encabezado (por ejemplo, a1b2c3d4e5f6789...). Este campo está enmascarado y almacenado de forma segura. También puedes utilizar un activo de credenciales para este campo.

    Configura la misma clave de encabezado y valor en la configuración de webhook del proveedor. Si los valores no coinciden en el tiempo de ejecución, UiPath rechaza la solicitud con HTTP 401.

    Para obtener más información, consulta Autenticación de encabezado de Webhook.

    For JWT Authentication, specify:

    • Key type — select Passphrase to verify tokens with a shared secret, or PEM Key to verify them with a public key.
    • JWT secret (for Passphrase) — the shared secret that the sender uses to sign the token.
    • JWT public key (for PEM Key) — the PEM-encoded public key that verifies the token signature, including the BEGIN and END lines.
    • JWT algorithm — the algorithm that the sender uses to sign the token. The default is HS256 for Passphrase and RS256 for PEM Key.

    The sender must send a signed JWT in the Authorization: Bearer <your-access-token> header of every request. If the token is missing, not valid, or expired, UiPath rejects the request with HTTP 401.

    For more information, see Webhook JWT authentication.

  7. Configurar la ubicación del desafío
    Elige cómo enviará el proveedor el token de desafío para que UiPath pueda responder correctamente:

    • Sin desafío : el proveedor no requiere un apretón de manos y puedes proceder a conectarte.
    • Parámetro de consulta (por ejemplo, ?challenge=...)
    • Cuerpo JSON (POST con { "challenge": "..." })
    • Encabezado (por ejemplo, X-Hub-Challenge)
  8. Configure la verificación de desafío y conéctese
    Si el proveedor requiere un protocolo de enlace, introduce la verificación de desafío que coincida con el patrón del proveedor (qué campo/encabezado/consulta leer y cómo repetirlo/validarlo). Cuando se complete la configuración, selecciona Conectar.

    Cuando esté disponible, selecciona el menú junto a un campo y elige Usar activo de credenciales o Usar activo de Orchestrator para hacer referencia a un activo de Orchestrator en lugar de introducir el valor directamente. Para obtener más información, consulta Usar activos de credenciales para las conexiones.

Consejo:
  • Utiliza un nombre que incluya el proveedor y el entorno (por ejemplo, Stripe-prod o Slack-staging) para evitar confusiones.
  • Si no estás seguro de qué patrón de desafío utiliza el proveedor, consulta sus documentos de webhook o ejecuta un registro de prueba para inspeccionar la solicitud de handshake.

Verificación de desafío de Webhook​

Algunos proveedores requieren que se validen las URL de webhook antes de comenzar a enviar eventos reales. Esto se hace utilizando un mecanismo de desafío-respuesta. Cuando registras un webhook, el proveedor envía una solicitud de desafío especial y el punto final debe responder exactamente como se espera.

El conector HTTP Webhook admite estos flujos de verificación a través del marco de desafíos de Webhook, lo que te permite configurar cómo UiPath debe leer y responder a los desafíos del proveedor.

Compatibilidad con la verificación de desafíos​

UiPath admite ambos tipos de comportamientos de webhook de proveedor:

  • Proveedores que no utilizan la verificación de desafío
  • Proveedores que requieren un protocolo de enlace de desafío antes de activar el webhook

Esto garantiza la compatibilidad con proveedores de webhooks simples, así como con aquellos con requisitos de seguridad más avanzados.

Cuando los proveedores no utilizan la verificación por desafío​

Muchas aplicaciones simplemente aceptan una URL de webhook y comienzan a entregar eventos de inmediato.
Para estos proveedores:

  • Los usuarios solo necesitan crear o seleccionar una conexión.
  • Copia la URL del webhook.
  • Pégalo en la configuración de webhook del proveedor.

No se requieren pasos adicionales. El webhook se activa tan pronto como el proveedor comienza a enviar eventos.

Este es el escenario más común y sencillo, y UiPath lo gestiona sin problemas.

Cuando los proveedores requieren verificación de desafío​

Algunos proveedores envían una solicitud de desafío para verificar la URL del webhook antes de habilitarla.
En estos casos:

  • Los usuarios deben configurar la respuesta de desafío en la conexión HTTP Webhook.
  • UiPath escucha la solicitud de desafío del proveedor.
  • UiPath devuelve automáticamente el valor de desafío correcto en función de la configuración.
  • Una vez que el proveedor valida la respuesta, los eventos normales comienzan a fluir.

Debido a que los proveedores difieren en la forma en que envían el desafío (parámetro de consulta, cuerpo JSON, encabezado, etc.), la configuración de UiPath permite a los usuarios manejar cualquiera de estos patrones.

Esto garantiza la compatibilidad con los proveedores de webhooks que imponen protocolos de enlace de seguridad como Slack, Meta (Facebook/Instagram), Stripe y otros.

Configurar la verificación de desafío​

El comportamiento de desafío se configura utilizando cuatro parámetros:

  • Clave de desafío
    Campo/clave que contiene el valor de desafío. Se utiliza para detectar solicitudes de desafío (no debe ser nulo).

  • Ubicación del desafío
    Donde aparece la clave:

    • Cuerpo
    • Parámetro de consulta
    • Encabezado
  • Tipo de contenido de la respuesta al desafío
    Formato de la respuesta devuelta al proveedor:

    • texto/sin formato
    • application/json
  • Formato de respuesta al desafío
    Define qué valor se devuelve (normalmente la propia clave de desafío).
    UiPath extrae el valor del desafío entrante y responde en consecuencia.

Ejemplos de configuración de desafío​

Ejemplo genérico​
Solicitud entrante​
 {
  "challenge": "ABC123"
 }
 {
  "challenge": "ABC123"
 }

Configuración

  • Clave de desafío: challenge != null
  • Ubicación del desafío: cuerpo
  • Tipo de respuesta: text/plain
  • Formato de respuesta: challenge
Respuesta​

ABC123

Ejemplo de verificación de desafío de WhatsApp​

WhatsApp utiliza el método de desafío basado en parámetros de consulta con hub.challenge.

Configuración​
ParámetroValor
Clave de desafíohub.challenge != null
Ubicación del desafíoParámetro de consulta
Tipo de contenido de la respuesta al desafíotext/plain
Formato de respuesta al desafíohub.challenge
Solicitud de proveedor​

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

Respuesta esperada de UiPath​
HTTP/1.1 200 OK
Content-Type: text/plain

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

1234567890

Esto confirma la propiedad y WhatsApp comienza a enviar eventos de webhook reales después.

Resumen: genérico frente a WhatsApp​
PasoEjemplo genéricoEjemplo de WhatsApp
Ubicación del desafíoCuerpo/Consulta/EncabezadoConsulta
Formato de claveClave simple (por ejemplo, challenge)Clave con punto ("hub.challenge")
TipoDeRespuestatexto/sin formato o aplicación/jsontexto/sin formato
Valor de respuestaValor de la claveValor de "hub.challenge"
MétodoPUBLICAR u OBTENERSolo OBTENER

Ejemplos por patrón de proveedor​

Ejemplo 1: desafío de cuerpo simple con respuesta de texto​
Envíos del proveedor​

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

CampoValor
Ubicación del desafíoBody
Clave de desafíochallenge
Tipo de contenido de la respuesta al desafíotext
Formato de respuesta al desafíochallenge

Respuesta: abc123 (texto/sin formato, 200)

Ejemplo 2: desafío de parámetro de consulta con respuesta de texto​
Envíos del proveedor​

GET /webhook?challenge=CHALLENGE_STRING

CampoValor
Ubicación del desafíoQuery Parameter
Clave de desafíochallenge
Tipo de contenido de la respuesta al desafíotext
Formato de respuesta al desafíochallenge

Respuesta: CHALLENGE_STRING (texto/sin formato, 200)

Ejemplo 3: Desafío de cuerpo con respuesta JSON​
Envíos del proveedor​

{"challenge":"abc123"}

CampoValor
Ubicación del desafíoBody
Clave de desafíochallenge
Tipo de contenido de la respuesta al desafíojson
Formato de respuesta al desafío{ "challenge": "challenge" }

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

Ejemplo 4: ruta del cuerpo anidado (por ejemplo, verification.token) con respuesta de texto​
Envíos del proveedor​

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

CampoValor
Ubicación del desafíoBody
Clave de desafíoverification.token
Tipo de contenido de la respuesta al desafíotext
Formato de respuesta al desafíoverification.token

Respuesta: abc123 (texto/sin formato, 200)

Ejemplo 5: ruta profundamente anidada con respuesta JSON​
Envíos del proveedor​

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

CampoValor
Ubicación del desafíoBody
Clave de desafíoevent.challenge
Tipo de contenido de la respuesta al desafíojson
Formato de respuesta al desafío{ "result": "event.challenge" }

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

Ejemplo 6: Desafío basado en encabezado (nombre de encabezado con guiones) con respuesta de texto​
Envíos del proveedor​

POST /webhook x-webhook-challenge: abc123

CampoValor
Ubicación del desafíoHeader
Clave de desafío"x-webhook-challenge"
Tipo de contenido de la respuesta al desafíotext
Formato de respuesta al desafío"x-webhook-challenge"

Respuesta: abc123 (texto/sin formato, 200)

Nota:

El nombre del encabezado contiene guiones, que pueden malinterpretarse como operadores en contextos de análisis. Envolver el identificador entre comillas dobles (por ejemplo, "x-webhook-challenge") garantiza que se trate como un nombre de clave literal. Utiliza siempre comillas dobles alrededor de cualquier identificador que contenga guiones, puntos u otros caracteres especiales.

Ejemplo 7: Detección booleana con diferente clave de respuesta​
Envíos del proveedor​

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

Quiere detectar por el campo type pero responde con el valor challenge .

CampoValor
Ubicación del desafíobody
Clave de desafíotype == url_verification``
Tipo de contenido de la respuesta al desafíojson
Formato de respuesta al desafío{ "challenge": "challenge" }

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

Autenticación de encabezado de webhook​

La autenticación basada en encabezados permite a UiPath validar cada solicitud de webhook entrante con un secreto compartido que configuraste en la creación de la conexión. Esto evita que las personas no autorizadas desencadenen tus flujos de trabajo publicando en tu URL de webhook.

Cómo funciona​

Cuando la autenticación basada en encabezado está habilitada en una conexión, Integration Service:

  1. Comprueba cada solicitud entrante para la clave de encabezado configurada.
  2. Acepta el evento si el encabezado está presente y su valor coincide con el secreto almacenado.
  3. Devuelve HTTP 401 no autorizado y no desencadena ningún flujo de trabajo si el encabezado está ausente o su valor no coincide.

autenticación de encabezado de webhook

Solicitud de ejemplo que UiPath acepta:

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

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

{ "event": "..." }

Solicitud de ejemplo que UiPath rechaza (falta encabezado o valor incorrecto):

HTTP/1.1 401 Unauthorized
HTTP/1.1 401 Unauthorized

Campos de configuración​

La siguiente tabla describe los campos que te permiten configurar la autenticación de encabezado de webhook en la pantalla de creación de conexión.

CampoDescripciónEjemplo
Tipo de AutenticaciónHabilita o deshabilita la validación de encabezado para esta conexión.Header Based Authentication / None
Clave de encabezadoNombre del encabezado HTTP que envía el proveedor.X-API-Key, X-API-Secret
Valor del encabezadoValor secreto que el proveedor envía en ese encabezado. Enmascarado en reposo.a1b2c3d4e5f6789...

Compatibilidad del proveedor​

La autenticación basada en encabezado solo funciona con proveedores que te permiten configurar un encabezado HTTP personalizado en las entregas de webhook salientes.

Si no estás seguro de si tu proveedor admite encabezados personalizados de salida, consulta la documentación de webhook del proveedor.

Actualizar o rotar el secreto​

Al editar la conexión y cambiar el valor del encabezado, el nuevo valor entra en vigor inmediatamente para todos los desencadenadores que utilizan esa conexión. La configuración del proveedor debe actualizarse con el nuevo valor al mismo tiempo, o las entregas del proveedor fallarán con HTTP 401 hasta que lo hagas.

Comportamiento cuando falla la autenticación​

Se rechaza una solicitud con HTTP 401 no autorizado si:

  • El encabezado esperado está ausente en la solicitud.
  • El encabezado está presente, pero su valor no coincide con el secreto almacenado.

UiPath no vuelve a intentar las solicitudes fallidas y no se envía ningún evento desencadenador. Se aplica el propio comportamiento de reintento del proveedor (si lo hubiera).

Los seguimientos de fallos de autenticación se pueden ver en la sección Seguimientos . Para ayudar a proteger nuestros sistemas de los ataques DoS, los seguimientos de fallos de autenticación se limitan a 5 por hora.

Notas importantes​

  • La autenticación basada en encabezado tiene un ámbito de conexión. Todos los desencadenadores creados para la misma conexión comparten la misma clave de encabezado y valor: actualizar el secreto de la conexión afecta a todos los desencadenadores que lo utilizan.
  • La autenticación basada en encabezado es independiente de la verificación de desafío. En una conexión se pueden habilitar ambos, ambos o ninguno.
  • El valor del encabezado se almacena cifrado y debe tratarse con el mismo cuidado que cualquier otra credencial.
  • Los nombres de encabezado no distinguen entre mayúsculas y minúsculas según la especificación HTTP (X-API-Key y x-api-key son equivalentes).

Webhook JWT authentication​

Nota:

JWT authentication, query parameter filters, and the query parameter outputs are available only in Automation Cloud.

JWT authentication lets UiPath validate every incoming webhook request with a signed JSON Web Token (JWT). The sender signs a token with a secret or a private key and sends it in the Authorization header. UiPath verifies the token with the key that you configured on the connection. Unlike a static header value, a token expires, so a leaked token stops working after its expiration time.

How JWT authentication works​

When JWT authentication is enabled on a connection, Integration Service does these checks on every incoming request, including challenge requests:

  1. Reads the token from the Authorization: Bearer <your-access-token> header.
  2. Verifies the token signature with the key and the algorithm configured on the connection.
  3. Checks that the token has an exp (expiration time) claim and that the token has not expired. If the token has an nbf (not before) claim, UiPath accepts the token only after that time.
  4. Accepts the event if all the checks pass. If a check fails, UiPath returns HTTP 401 Unauthorized and does not trigger any workflow.
Example request that UiPath accepts​
POST /<organization>/<tenant-id>/elements_/v1/webhooks/events/<webhook-id> HTTP/1.1
Host: cloud.uipath.com
Authorization: Bearer <your-access-token>
Content-Type: application/json

{ "event": "..." }
POST /<organization>/<tenant-id>/elements_/v1/webhooks/events/<webhook-id> HTTP/1.1
Host: cloud.uipath.com
Authorization: Bearer <your-access-token>
Content-Type: application/json

{ "event": "..." }

JWT configuration fields​

The following table describes the fields that let you configure webhook JWT authentication on the connection creation screen.

CampoDescripciónEjemplo
Tipo de AutenticaciónSelect JWT Authentication to validate a JWT on every request for this connection.JWT Authentication
TipodeClaveHow UiPath verifies the token signature. Passphrase uses a shared secret. PEM Key uses a public key.Passphrase / PEM Key
JWT secretShown when Key type is Passphrase. The shared secret that the sender uses to sign the token.A random value of 32 or more characters
JWT public keyShown when Key type is PEM Key. The PEM-encoded RSA or EC public key that verifies the signature, including the BEGIN and END lines.-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----
JWT algorithmThe algorithm that the sender uses to sign the token. It must match the key type.HS256 (default for Passphrase), RS256 (default for PEM Key)

Supported algorithms​

TipodeClaveClaveAlgorithms
PassphraseShared secretHS256, HS384, HS512
PEM KeyRSA public keyRS256, RS384, RS512, PS256, PS384, PS512
PEM KeyEC public keyES256 (P-256), ES384 (P-384), ES512 (P-521)

UiPath uses only the algorithm configured on the connection. The alg value in the token header must match it. UiPath always rejects unsigned tokens (alg: none).

For Passphrase, use a random secret of at least 32 characters for HS256, 48 characters for HS384, or 64 characters for HS512.

For PEM Key, keep the private key with the sender and paste only the public key into the connection. If the JWT public key field contains a private key, every request fails authentication.

Token requirements​

The sender must:

  • Send the token in the Authorization header with the Bearer scheme. UiPath does not read tokens from query parameters or from other headers.
  • Sign the token with the configured key and algorithm.
  • Include an exp claim in the token. UiPath rejects tokens that do not have an exp claim.

UiPath does not check other claims, such as iss, aud, or sub. There is no grace period for the exp and nbf claims, so make sure that the clock of the sender is accurate.

Vendor compatibility for JWT authentication​

JWT authentication works only with senders that can create a signed JWT and send it in the Authorization header of each webhook request. For example, your own service or an integration platform that you control. If you are not sure, check the webhook documentation of the sender.

JWT authentication failures​

UiPath rejects a request with HTTP 401 Unauthorized if:

  • The Authorization header is absent, or it does not use the Bearer scheme.
  • The token signature does not match the configured key, or the token uses a different algorithm.
  • The token does not have an exp claim, has expired, or is used before its nbf time.
  • The JWT settings of the connection are not valid. For example, the algorithm does not match the key type, or the JWT public key field does not contain a PEM-encoded public key.

UiPath does not check the JWT settings when you create the connection. An incorrect setting shows only when requests start to fail.

The response contains one of these messages:

CausaMensaje
No bearer token in the requestAuthentication failed. The request did not include a bearer token in the Authorization header.
All other failuresAuthentication failed. The bearer token in the Authorization header is invalid or expired.

Failed requests are not retried by UiPath, and no trigger event is dispatched. Authentication failure traces work the same way as for header-based authentication. For details, see Behavior when authentication fails.

The token in the trigger output​

After UiPath verifies a token, it masks the token in the event. In the output of the HTTP Webhook trigger and of the Get Trigger Event Output activity, the Authorization header keeps only the first five characters of the token, for example Bearer eyJhb*****. This prevents a person who can read the event from using the token again.

JWT important notes​

  • JWT authentication is connection-scoped. All triggers created against the same connection use the same key — updating the connection's key affects every trigger using it.
  • When you change the key on the connection, update the sender at the same time. Tokens signed with the old key fail authentication.
  • UiPath checks the token on every request, including challenge requests. If your vendor sends a challenge request, the challenge request must also contain a valid token.
  • Store the JWT secret with the same care as any other credential.

¿Te ha resultado útil esta página?

Conectar

¿Necesita ayuda? Soporte(opens in new window)

¿Quiere aprender? UiPath Academy(opens in new window)

¿Tiene alguna pregunta? Foro de UiPath(opens in new window)

Manténgase actualizado