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.

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.

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:

{
  "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:

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.

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:

{
  "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`

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.

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.

Getting started

Build

Operate

Deploy

Reports

Account

Webhook

Using the Webhook block

Listener URL

Getting the conversation key

Expected payload

Example request

Response mapping

Timeout

Authentication

Output paths

Success

Failure

Save response to variables

​Using the Webhook block

​Listener URL

​Getting the conversation key

​Expected payload

​Example request

​Response mapping

​Timeout

​Authentication

​Output paths

​Success

​Failure

​Save response to variables

Using the Webhook block

Listener URL

Getting the conversation key

Expected payload

Example request

Response mapping

Timeout

Authentication

Output paths

Success

Failure

Save response to variables