> ## Documentation Index
> Fetch the complete documentation index at: https://help.wotnot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

> Configure your WotNot account, including account-level settings, timezone, branding, and security options.

These settings control how your account operates and how users access it. Some settings affect the entire account, while others apply only to your own profile.

![Image](https://mintcdn.com/wotnot/9dFb9jDqAX6_tYFX/images/image-286.png?fit=max\&auto=format\&n=9dFb9jDqAX6_tYFX\&q=85\&s=c19e11637045107a64b8b5564727460f)

> [!NOTE]
>
> Available on the **PREMIUM** plan and above

Webhooks are used to listen to events occurring on a third-party app. It is most commonly used for use cases like payment collection, where the chatbot waits for the third-party payment processor to call the webhook once payment is received.

# Using the Webhook block

### Listener URL

The **Listener URL** is generated automatically when you add the Webhook block.

Copy this URL and configure it as the webhook endpoint in the external system that will send the event.

When the external system sends an event, the incoming request must contain the `conversation_key` associated with the conversation waiting for the event.

> [!NOTE]
>
> The `conversation_key` connects the external event to the correct conversation. Make sure your external system sends the same `conversation_key` associated with the waiting conversation.

### Getting the conversation key

You can use the variable **Conversation URL** to extract the conversation\_key value from it.

Use a javascript action block before using the webhook block with this code.

```javascript theme={null}
const conversation_url = "Conversation URL";

// Function to extract the conversation key from the URL
function getLastPartOfUrl(url) {
    // Split the URL by slashes
    const parts = url.split('/');

    // Return the last part
    return parts[parts.length - 1];
}

// Retrieve the conversation key from the URL
const conversation_key = getLastPartOfUrl(conversation_url);

// Sets the conversation key into a new variable
wn.setConversationVariable("conversation_key", conversation_key);

// This variable will be used to push the conversation_key to the third-party app.
```

Pass this `conversation_key` to your external system when starting the process that will eventually trigger the webhook.

For example, if a user starts a payment, store the conversation key along with the payment reference. When the payment is completed, your integration can send the same conversation key back to WotNot.

## Expected payload

The external system should send the `conversation_key` along with the event data.

For example:

```json theme={null}
{
  "conversation_key": "abc123xyz",
  "event": "payment_success",
  "payment_id": "PAY-12345",
  "status": "success",
  "amount": 499
}
```

The `conversation_key` identifies the conversation that is waiting for the event.

The remaining fields contain the event data that you can map to variables and use in the flow.

### Example request

You can test the Webhook block using cURL:

```bash theme={null}
curl --request POST \
  --url '<LISTENER_URL>' \
  --header 'Content-Type: application/json' \
  --data '{
    "conversation_key": "abc123xyz",
    "event": "payment_success",
    "payment_id": "PAY-12345",
    "status": "success",
    "amount": 499
  }'
```

Replace `<LISTENER_URL>` with the Listener URL generated by the Webhook block.

Replace `abc123xyz` with the `conversation_key` of the conversation waiting for the event.

> [!TIP]
>
> The `conversation_key` in the incoming request must match the conversation waiting at the Webhook block. Otherwise, WotNot cannot resume the correct conversation.

## Response mapping

When a webhook response is received, you can map the fields that are to be saved into variables.

For example, if the incoming payload is:

```json theme={null}
{
  "conversation_key": "abc123xyz",
  "payment_id": "PAY-12345",
  "status": "success",
  "amount": 499
}
```

You can map the fields as follows:

| Payload field | Variable |
| - | - |
| `payment_id` | `payment_id` |
| `status` | `payment_status` |
| `amount` | `payment_amount` |

> [!NOTE]
>
> You can map a maximum of 50 variables.

## Timeout

The chat flow will wait for this webhook call for the specified duration.

If the webhook is not invoked in the given timeframe, the chat flow will proceed in the FAILURE flow.

> [!NOTE]
>
> Set the timeout between **1 and 300 seconds**.

## Authentication

If your external system requires authentication for the incoming webhook request, configure the required authentication or secret according to your integration requirements.

Make sure authentication credentials and secrets are stored securely and are not exposed in user-visible messages or variables.

## Output paths

The Webhook block has two possible outcomes.

### Success

The incoming webhook event is received and the conversation continues through the **Success** path.

### Failure

The webhook is not received within the configured timeout and the conversation continues through the **Failure** path.

Connect the appropriate paths to handle both outcomes in your flow.

## Save response to variables

The Webhook block can save fields from the incoming payload through **Response mapping**.

| Payload field | Variable |
| - | - |
| `payment_id` | `payment_id` |
| `status` | `payment_status` |
| `amount` | `payment_amount` |
| `order_status` | `order_status` |

You can also map other fields included in the incoming payload.

The `conversation_key` is used to identify the conversation waiting for the event.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.