Webhook action

This is the recommended way to call an external API with OpenDialog.

Webhook actions allows you to make calls to an external APIs via HTTP protocol.

You can create new webhook action by visiting your scenario -> Integreate -> Actions -> Create webhook integration:

Configuring webhook action

Overview

Action Name: Enter a descriptive action name.
Description (optional): Add contextual information to clarify the function and necessity of this action.
HTTP Verb Selection: Choose an HTTP method for the URL (GET, POST, PUT, DELETE, PATCH).
URL: Enter the complete URL, including the scheme, domain, path, and parameters.
Headers: Specify the headers to send with your request.
Request Body: Set up the request payload if required. Currently only application/json is supported (the Content-Type: application/json header is added automatically).
Response: Define how to process response payload. Only mapping for application/json responses is supported for now.
Testing Panel: You can test your webhook once the name, method, and URL are configured.

Basic configuration

Name
- Required;
- Up to 60 characetrs;
Description
- Optional;
- Up to 120 characters;
HTTP Method
- Single-choice select with options GET, POST, PUT, DELETE, PATCH
URL
- Must be a valid URL to your API resource
- It supports OD attribute syntax like in messages with context and filters. You can use it to parametrise host name, path segment or query parameters. Resulting value is automatically URL encoded. Fore example: https://yourapi.com/api/{api_version}/users?userId={user_id}

Headers configuration

Configure key-value pairs for your headers. Value field also supports the OD attribute syntax, allowing users to insert dynamically resolved data into the header value, offering powerful flexibility for authentication, correlation tracking, or transmitting system-specific metadata within the webhook call.

Request configuration

Put a JSON payload which should be sent with your request.

OD attribute syntax is supported, but you have to put them in double-quotes.

✅ Do

{
    "firstName": "{first_name}"
}

❌ Don't

{
    "firstName": {first_name}
}

Attribute types are preserved when the action is executing, so your number, boolean etc. attributes will be sent accordingly.

Response configuration

In the "Status and Response Mapping" section, configure how to store and map output from the webhook. Each mapping is grouped by status code categories:

1xx: Status codes from 100 to 199;
2xx: Status codes from 200 to 299;
3xx: Status codes from 300 to 399;
4xx: Status codes from 400 to 499;
5xx: Status codes from 500 to 599.

Within each group, configure the following individually:

action_success

Determines what constitutes a successful execution of your action. This sets the attribute <action_name>_action_success.

Value must be set to one of the following:

TRUE
FALSE
JMESPath expression pointing to a boolean property from a JSON payload.

Default values:

TRUE for groups 1xx, 2xx, 3xx;
FALSE for groups 4xx, 5xx.

Note: Webhook actions will not automatically follow redirects in response to 3xx status codes.

Output attribute mapping

Under the action_success mapping, you can specify output attributes for your webhook action. These attributes are populated into the user context by default and can be accessed in your conversation design using the {attribute_name} or {user.attribute_name} syntax.

For a simple use case, just put the property name from your response JSON next to the desired OD attribute name. To store a nested property, use dot notation (e.g., user.profile.name).

For more complex mapping and response transformations, use JMESPath.

Store raw response

You can store the whole response as a string by toggling "Store raw response" and selecting a string attribute to contain this value.

Testing your webhook

Once you fill in your action name, URL, and HTTP method, the testing panel will become available, allowing you to run a test execution of your action.

Inputs block

Any input attributes in the URL, headers, and request body sections will become available to fill in. These temporary values will be used during your tests.

Outputs & Attributes block

You can see if your action worked as expected in the Outputs section. A green check will indicate if the action was executed successfully, and the response status code will be displayed next to it. In the Attributes section, you will see three default output attributes plus any output attributes you've defined in the "Response" tab:

<action_name>_action_success: A true/false value indicating whether your action was successful or not. You can customise this value in the "Response" tab for each status code group.
action_success: Same as above; this is a reusable default attribute which will be overridden by the next action you have in your actions pipeline.
<action_name>_status_code: An integer value with the HTTP response status code.

Response block

Use this section to view detailed information about your response, including exact values of your headers, URL, and body that were sent. Additionally, it shows the response headers and raw response body received by the webhook.

Use the pop-out icon next to the "Response" section to view this in a full-page modal for more convenience.

Using your webhook in conversation

Once you've saved your webhook action, it will appear on the "Actions" page. For convenience, a small chip with the HTTP method will be displayed in the bottom-left corner of the action card. Legacy webhook actions will be displayed with the subtitle "Legacy Webhook Action" and can be used as usual.

Attach your webhook action as usual to an intent in the conversation designer.

When the conversation reaches this intent, all your defined actions will be executed.

Previous3rd party Integrations in your application NextExecution logs and troubleshooting

Last updated 17 days ago