- Getting started
- Notifications
- Licensing
- Troubleshooting
- Coding agents
- Connector Builder
- Act! 365
- ActiveCampaign
- Active Directory - Preview
- Adobe Acrobat Sign
- Adobe PDF Services
- Agent 2 Agent - Preview
- Amazon Bedrock
- Amazon Connect
- Amazon Polly
- Amazon SES
- Amazon Transcribe
- Amazon Web Services
- Anthropic Claude
- Asana
- AWeber
- Azure AI Document Intelligence
- Azure Defender for Cloud
- Azure Maps
- BambooHR
- Box
- Brevo
- Calendly
- Campaign Monitor
- Cisco Webex Teams
- Citrix Hypervisor
- Citrix ShareFile
- Clearbit
- Confluence Cloud
- Constant Contact
- Coupa
- CrewAI – Preview
- Customer.io
- Database Hub
- Databricks - Preview
- Databricks Agent
- Datadog
- DeepSeek
- Deputy
- Discord - Preview
- DocuSign
- Drip
- Dropbox
- Dropbox Business
- Egnyte
- Epic FHIR - Preview
- Eventbrite
- Exchangerates
- Exchange Server - Preview
- Expensify
- Facebook
- Freshbooks
- Freshdesk
- Freshsales
- Freshservice
- GetResponse
- GitHub
- Gmail
- Google Cloud Platform
- Google Docs
- Google Drive
- Google Forms - Preview
- Google Maps
- Google Sheets
- Google Speech-to-Text
- Google Text-to-Speech
- Google Tasks - Preview
- Google Vertex
- Google Vision
- Google Workspace
- GoToWebinar
- Greenhouse
- Hootsuite
- HTTP
- HTTP Webhook
- About the HTTP Webhook connector
- HTTP Webhook authentication
- HTTP Webhook events
- Using the Webhook connector
- Monitoring
- Hubspot CRM
- HubSpot Marketing
- HyperV - Preview
- Icertis
- iContact
- Insightly CRM
- Intercom
- Jina.ai
- Jira
- Keap
- Klaviyo
- LinkedIn
- Mail
- Mailchimp
- Mailgun
- Mailjet
- MailerLite
- Marketo
- MCP
- Microsoft 365
- Microsoft Azure
- Microsoft Azure Active Directory
- Microsoft Azure AI Foundry
- Microsoft Azure OpenAI
- Microsoft Azure Sentinel
- Microsoft Dynamics 365 CRM
- Microsoft OneDrive & Sharepoint
- Microsoft Outlook 365
- Microsoft Power Automate
- Microsoft Sentiment
- Microsoft Sentinel Threat Intelligence
- Microsoft Teams
- Microsoft Translator
- Microsoft Vision
- Miro
- NetIQ eDirectory
- Nvidia NIM
- Okta
- OpenAI
- OpenAI V1 Compliant LLM
- Oracle Eloqua
- Oracle NetSuite
- PagerDuty
- PayPal
- PDFMonkey
- Perplexity
- Pinecone
- Pipedrive
- QuickBooksOnline
- Quip
- Salesforce
- Salesforce Agentforce & Flows
- Salesforce Marketing Cloud
- SAP BAPI
- SAP Cloud for Customer
- SAP Concur
- SAP OData
- SendGrid
- ServiceNow
- Shopify
- Slack
- SmartRecruiters
- Smartsheet
- Snowflake
- Snowflake Cortex
- Stripe
- Sugar Enterprise
- Sugar Professional
- Sugar Sell
- Sugar Serve
- System Center - Preview
- TangoCard
- Todoist
- Trello
- Twilio
- TypeSafe - Preview
- UiPath Apps - Preview
- UiPath Data Fabric
- UiPath Test Manager
- UiPath GenAI Activities
- UiPath Orchestrator
- X (formerly Twitter)
- Xero
- watsonx.ai
- WhatsApp Business
- WooCommerce
- Workable
- Workday
- Workday REST
- VMware ESXi vSphere
- YouTube
- Zendesk
- Zoho Campaigns
- Zoho Desk
- Zoho Mail
- Zoom
- ZoomInfo
HTTP Webhook authentication
Connect UiPath to your webhook provider and configure webhook challenge verification, header-based authentication, or JWT authentication.
Prerequisites
Your webhook provider may require a handshake. Refer to the Webhook challenge verification section for details on how to configure the challenge verification.
Depending on where you create the trigger, the generated webhook URL will appear either in the HTTP Webhook trigger activity or on the trigger creation page, but only after the connection is created successfully. To avoid failures, paste the webhook URL into your application after you publish your workflow or the trigger is successfully created in UiPath Orchestrator.
Creating an HTTP Webhook connection
-
Select Orchestrator from the product launcher.
-
Select a folder, and then navigate to the Connections tab.
-
Select Add connection.
-
To open the connection creation page, select the connector from the list. You can use the search bar to find the connector.
-
In the What application is this webhook for field, enter a descriptive name for the webhook application, something that makes it easy to identify which vendor or integration this connection represents. This value becomes the Connection Identifier.
-
(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:
- Header key — the HTTP header the vendor uses to send the credential (for example,
X-API-KeyorX-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.
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
BEGINandENDlines. - JWT algorithm — the algorithm that the sender uses to sign the token. The default is
HS256for Passphrase andRS256for 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.
- Header key — the HTTP header the vendor uses to send the credential (for example,
-
Configure the Challenge location
Choose how the vendor will send the challenge token so that UiPath can respond correctly:- No challenge - the vendor does not require a handshake, and you can proceed to connect.
- Query parameter (e.g.,
?challenge=...) - JSON body (POST with
{ "challenge": "..." }) - Header (e.g.,
X-Hub-Challenge)
-
Configure the challenge verification and connect
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.
- Use a name that includes the vendor and environment (for example, Stripe-prod or Slack-staging) to avoid confusion.
- If you're unsure which challenge pattern the vendor uses, check their webhook docs or run a test registration to inspect the handshake request.
Webhook challenge verification
Some vendors require webhook URLs to be validated before they start sending real events. This is done using a challenge–response mechanism. When you register a webhook, the vendor sends a special challenge request, and the endpoint must respond exactly as expected.
The HTTP Webhook connector supports these verification flows through the Webhook Challenges Framework, allowing you to configure how UiPath should read and respond to vendor challenges.
Challenge verification support
UiPath supports both types of vendor webhook behaviors:
- Vendors that do not use challenge verification
- Vendors that require a challenge handshake before activating the webhook
This ensures compatibility with simple webhook providers as well as those with more advanced security requirements.
When vendors do not use challenge verification
Many applications simply accept a webhook URL and start delivering events immediately.
For these vendors:
- Users only need to create or select a connection.
- Copy the webhook URL.
- Paste it into the vendor's webhook configuration.
No additional steps are required. The webhook becomes active as soon as the vendor starts sending events.
This is the most common and simplest scenario, and UiPath handles it seamlessly.
When vendors do require challenge verification
Some vendors send a challenge request to verify the webhook URL before enabling it.
In these cases:
- Users must configure the challenge response in the HTTP Webhook connection.
- UiPath listens for the vendor's challenge request.
- UiPath automatically returns the correct challenge value based on the configuration.
- Once the vendor validates the response, normal events begin to flow.
Because vendors differ in how they send the challenge (query param, JSON body, header, etc.), UiPath's configuration allows users to handle any of these patterns.
This ensures compatibility with webhook providers that enforce security handshakes such as Slack, Meta (Facebook/Instagram), Stripe, and others.
Configuring challenge verification
You configure challenge behavior using four parameters:
-
Challenge Key
Field/key containing the challenge value. Used to detect challenge requests (must not be null). -
Challenge Location
Where the key appears:- Body
- Query parameter
- Header
-
Challenge Response Content Type
Format of the response returned back to the vendor:- text/plain
- application/json
-
Challenge Response Format
Defines which value is returned (usually the challenge key itself).
UiPath extracts the value from the incoming challenge and responds accordingly.
Challenge configuration examples
Generic example
Incoming request
{
"challenge": "ABC123"
}
{
"challenge": "ABC123"
}
Configuration
- Challenge Key:
challenge != null - Challenge location: Body
- Response Type:
text/plain - Response Format:
challenge
Response
ABC123
WhatsApp challenge verification example
WhatsApp uses the query parameter–based challenge method with hub.challenge.
Configuration
| Parameter | Value |
|---|---|
| Challenge Key | hub.challenge != null |
| Challenge Location | Query parameter |
| Challenge Response Content Type | text/plain |
| Challenge Response Format | hub.challenge |
Vendor request
GET https://your-webhook-url?hub.challenge=1234567890
Expected UiPath response
HTTP/1.1 200 OK
Content-Type: text/plain
1234567890
HTTP/1.1 200 OK
Content-Type: text/plain
1234567890
This confirms ownership, and WhatsApp begins sending real webhook events afterward.
Summary—Generic vs WhatsApp
| Step | Generic Example | WhatsApp Example |
|---|---|---|
| Challenge Location | Body / Query / Header | Query |
| Key Fomat | Simple key (e.g., challenge) | Key with dot ("hub.challenge") |
| Response Type | text/plain or application/json | text/plain |
| Response Value | Value of the key | Value of "hub.challenge" |
| Method | POST or GET | GET only |
Examples by vendor pattern
Example 1: Simple body challenge with text response
Vendor sends
{"challenge":"abc123","type":"url_verification"}
| Field | Value |
|---|---|
| Challenge location | Body |
| Challenge key | challenge |
| Challenge response content type | text |
| Challenge response format | challenge |
Response: abc123 (text/plain, 200)
Example 2: Query param challenge with text response
Vendor sends
GET /webhook?challenge=CHALLENGE_STRING
| Field | Value |
|---|---|
| Challenge location | Query Parameter |
| Challenge key | challenge |
| Challenge response content type | text |
| Challenge response format | challenge |
Response: CHALLENGE_STRING (text/plain, 200)
Example 3: Body challenge with JSON response
Vendor sends
{"challenge":"abc123"}
| Field | Value |
|---|---|
| Challenge location | Body |
| Challenge key | challenge |
| Challenge response content type | json |
| Challenge response format | { "challenge": "challenge" } |
Response: {"challenge":"abc123"} (application/json, 200)
Example 4: Nested body path (e.g., verification.token) with text response
Vendor sends
{"verification":{"token":"abc123"}}
| Field | Value |
|---|---|
| Challenge location | Body |
| Challenge key | verification.token |
| Challenge response content type | text |
| Challenge response format | verification.token |
Response: abc123 (text/plain, 200)
Example 5: Deeply nested path with JSON response
Vendor sends
{"event":{"challenge":"abc123","type":"verify"}}
| Field | Value |
|---|---|
| Challenge location | Body |
| Challenge key | event.challenge |
| Challenge response content type | json |
| Challenge response format | { "result": "event.challenge" } |
Response: {"result":"abc123"} (application/json, 200)
Example 6: Header-based challenge (hyphenated header name) with text response
Vendor sends
POST /webhook x-webhook-challenge: abc123
| Field | Value |
|---|---|
| Challenge location | Header |
| Challenge key | "x-webhook-challenge" |
| Challenge response content type | text |
| Challenge response format | "x-webhook-challenge" |
Response: abc123 (text/plain, 200)
The header name contains hyphens, which can be misinterpreted as operators in parsing contexts. Wrapping the identifier in double quotes (e.g., "x-webhook-challenge") ensures it is treated as a literal key name. Always use double quotes around any identifier that contains hyphens, dots, or other special characters.
Example 7: Boolean detection with different response key
Vendor sends
{"type":"url_verification","challenge":"abc","token":"legacytoken"}
Want to detect by type field but respond with challenge value.
| Field | Value |
|---|---|
| Challenge location | body |
| Challenge key | type == url_verification`` |
| Challenge response content type | json |
| Challenge response format | { "challenge": "challenge" } |
Response: {"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.
How it works
When header-based authentication is enabled on a connection, Integration Service:
- Checks every incoming request for the configured header key.
- Accepts the event if the header is present and its value matches the stored secret.
- 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": "..." }
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
HTTP/1.1 401 Unauthorized
Configuration fields
The following table describes the fields that enable you to configure webhook header authentication on the connection creation screen.
| Field | Description | Example |
|---|---|---|
| Authentication Type | 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.
Important notes
- 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-Keyandx-api-keyare equivalent).
Webhook JWT authentication
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:
- Reads the token from the
Authorization: Bearer <your-access-token>header. - Verifies the token signature with the key and the algorithm configured on the connection.
- Checks that the token has an
exp(expiration time) claim and that the token has not expired. If the token has annbf(not before) claim, UiPath accepts the token only after that time. - 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.
| Field | Description | Example |
|---|---|---|
| Authentication Type | Select JWT Authentication to validate a JWT on every request for this connection. | JWT Authentication |
| Key type | How UiPath verifies the token signature. Passphrase uses a shared secret. PEM Key uses a public key. | Passphrase / PEM Key |
| JWT secret | Shown 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 key | Shown 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 algorithm | The 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
| Key type | Key | Algorithms |
|---|---|---|
| Passphrase | Shared secret | HS256, HS384, HS512 |
| PEM Key | RSA public key | RS256, RS384, RS512, PS256, PS384, PS512 |
| PEM Key | EC public key | ES256 (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
Authorizationheader with theBearerscheme. UiPath does not read tokens from query parameters or from other headers. - Sign the token with the configured key and algorithm.
- Include an
expclaim in the token. UiPath rejects tokens that do not have anexpclaim.
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
Authorizationheader is absent, or it does not use theBearerscheme. - The token signature does not match the configured key, or the token uses a different algorithm.
- The token does not have an
expclaim, has expired, or is used before itsnbftime. - 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:
| Cause | Message |
|---|---|
| No bearer token in the request | Authentication failed. The request did not include a bearer token in the Authorization header. |
| All other failures | Authentication 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.
- Prerequisites
- Creating an HTTP Webhook connection
- Webhook challenge verification
- Challenge verification support
- Configuring challenge verification
- Challenge configuration examples
- Examples by vendor pattern
- Webhook header authentication
- How it works
- Configuration fields
- Vendor compatibility
- Updating or rotating the secret
- Behavior when authentication fails
- Important notes
- Webhook JWT authentication
- How JWT authentication works
- JWT configuration fields
- Supported algorithms
- Token requirements
- Vendor compatibility for JWT authentication
- JWT authentication failures
- The token in the trigger output
- JWT important notes