HTTP Webhook 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

1. Select Orchestrator from the product launcher.
2. Select a folder, and then navigate to the Connections tab.
3. Select Add connection.
4. To open the connection creation page, select the connector from the list. You can use the search bar to find the connector.
5. 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.
6. 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)
7. 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, click Connect.

Tip:

• 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"
 }

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

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)

Note:

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)