# HTTP Webhook authentication

> Your webhook provider may require a handshake. Refer to the [Webhook challenge verification](https://docs.uipath.com/integration-service/automation-cloud/latest/user-guide/uipath-http-webhook-using-the-webhook-connector#webhook-challenge-verification) section for details on how to configure the challenge verification.

## Prerequisites

Your webhook provider may require a handshake. Refer to the [Webhook challenge verification](https://docs.uipath.com/integration-service/automation-cloud/latest/user-guide/uipath-http-webhook-using-the-webhook-connector#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](https://docs.uipath.com/integration-service/automation-cloud/latest/user-guide/uipath-http-webhook-authentication#webhook-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**.

   For any secret-type field, you can select the menu next to the field and choose **Use credential asset** to reference an Orchestrator credential asset linked to an external vault instead of entering the value directly. For more information, see [Use credential assets for connections](credential-store-connections.md).

:::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](https://developers.facebook.com/docs/whatsapp/webhooks/create-webhook-endpoint#request-syntax).

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

![](https://dev-assets.cms.uipath.com/assets/images/integration-service/whatsapp-challenge-f445f715.webp)

#### 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)