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. (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 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)

8. 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.

Challenge verification support​

• Vendors that do not use challenge verification
• Vendors that require a challenge handshake before activating the webhook

When vendors do not use challenge verification​

• Users only need to create or select a connection.
• Copy the webhook URL.
• Paste it into the vendor's webhook configuration.

When vendors do require challenge verification​

• 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.

Configuring challenge verification​

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

• Challenge Key: challenge != null
• Challenge location: Body
• Response Type: text/plain
• Response Format: challenge

Response​

WhatsApp challenge verification example​

Configuration​

Vendor request​

Expected UiPath response​

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

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

1234567890

Summary—Generic vs WhatsApp​

Examples by vendor pattern​

Example 1: Simple body challenge with text response​

Vendor sends​

Example 2: Query param challenge with text response​

Vendor sends​

Example 3: Body challenge with JSON response​

Vendor sends​

Example 4: Nested body path (e.g., verification.token) with text response​

Vendor sends​

Example 5: Deeply nested path with JSON response​

Vendor sends​

Example 6: Header-based challenge (hyphenated header name) with text response​

Vendor sends​

Example 7: Boolean detection with different response key​

Vendor sends​

How it works​

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.

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": "..." }

HTTP/1.1 401 Unauthorized
HTTP/1.1 401 Unauthorized

Configuration fields​

Vendor compatibility​

Updating or rotating the secret​

Behavior when authentication fails​

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

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-Key and x-api-key are equivalent).