Webhook action

Tip

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

New webhook page

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

Basic configuration

Example of basic configurations of webhook action

• 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

Example of headers configuration of webhook action

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

Example of payload configuration for webhook action

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

Example of response configuration for webhook action

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

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

Use testing panel on the left to run a test for 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.

Authentication configuration

Webhook V2 Actions support three authentication methods: Header Authentication, Mutual TLS (mTLS), and OAuth2 Client Credentials. Authentication is configured per webhook action, within the action configuration itself.

Select an authentication method for your webhook action

Note

All authentication methods are secret-aware. You can reference secrets from the Secret Context using {secret.your_secret_name} in your authentication configuration. Secret values are automatically decrypted during authentication and never appear in logs.

Header Authentication

Header Authentication lets you build dynamic authentication headers for your webhook requests. It supports two configuration blocks:

• variables: A JSON object of named values that are resolved lazily and can reference each other, OD attributes, and built-in _auth values.
• headers: A JSON object of header key-value pairs to be added to the request.

Both blocks support the full OD attribute syntax, including _auth context references, _webhook context references (for request body or URL), and standard user/global/secret attributes.

Header Authentication configuration

Using secrets in headers

Header Authentication is secret-aware — you can reference secrets from the Secret Context in your header values and variables. When the authentication executes, secret values are automatically decrypted and included in the outgoing request.

Caution

Secrets can only be decrypted within Webhook V2 authentication configurations. If you reference a secret attribute outside of authentication (for example, in a message template or the webhook URL), the value will appear as ••••••••.

Example: API key from the Secret Context

{
  "headers": {
    "Authorization": "Bearer {secret.api_key}",
    "X-Request-ID": "{_auth.uuid}"
  }
}

Built-in _auth variables

The following variables are automatically available in every Header Authentication configuration without any setup:

Variable	Description
{_auth.uuid}	A unique UUID generated per request
{_auth.timestamp}	Current Unix timestamp in seconds
{_auth.timestamp_micro}	Current Unix timestamp in microseconds

Variable chaining

Variables in the variables block can reference other variables defined in the same block, enabling you to build up values step by step. Resolution is lazy — each variable is only resolved when it is needed.

Example: HMAC signature with a secret

{
  "variables": {
    "secret": "{secret.hmac_signing_key}",
    "signature": "hmac-sha256({_webhook.body}, {_auth.secret})"
  },
  "headers": {
    "X-Request-ID": "{_auth.uuid}",
    "X-Signature": "{_auth.signature}",
    "X-Timestamp": "{_auth.timestamp}"
  }
}

Mutual TLS (mTLS) Authentication

mTLS authentication establishes a two-way TLS handshake between OpenDialog and your API. You provide a client certificate which is presented to the server during the TLS negotiation.

mTLS Authentication configuration

Configuration fields:

Field	Required	Description
Certificate	Yes	A certificate attribute from the Secret Context (e.g. {secret.my_cert})
Password	Yes	The password for the certificate — can be a secret (e.g. {secret.cert_password})
CA Certificate	No	Base64-encoded PEM CA certificate for verifying the server certificate

mTLS is secret-aware. The Certificate field expects a reference to a certificate stored in the Secret Context. Certificates can be uploaded in P12, PFX, PEM, CER, CRT, or KEY formats. The Password field can also reference a secret, keeping your certificate passphrase protected.

Example: using certificates and secrets from the Secret Context

Certificate: {secret.mtls_certificate}
Password:    {secret.cert_password}
CA Cert:     {global.mtls_ca_cert}

Note

To learn how to upload certificates and create secrets, see the Secret Context documentation.

OAuth2 Client Credentials

OAuth2 Client Credentials authentication is designed for server-to-server integrations where your webhook needs to authenticate with an OAuth2-protected API. It implements the OAuth2 Client Credentials Grant, which exchanges a client ID and client secret for an access token.

OAuth2 Client Credentials configuration

Configuration fields:

Field	Required	Supports secrets	Description
Token URL	Yes	No	The OAuth2 token endpoint URL
Client ID	Yes	No	Your application’s client identifier
Client Secret	Yes	Yes	Your application’s client secret — can be a secret attribute (e.g. {secret.oauth_client_secret})
Scope	No	No	Space-separated list of scopes to request

How it works

When your webhook action executes:

1. OpenDialog sends a token request to the Token URL with the client credentials
2. The token endpoint returns an access token
3. OpenDialog adds the token as a Bearer token in the Authorization header of your webhook request

Token caching

To avoid requesting a new token on every webhook call, OpenDialog automatically caches access tokens. Cached tokens are reused across follow-up calls to the same API. When a cached token is close to expiring, OpenDialog will request a fresh one.

Note

Each unique combination of client credentials and scope gets its own cached token. If you change the client ID, client secret, or scope, a new token will be requested.

Example

Token URL:     https://auth.example.com/oauth2/token
Client ID:     {global.oauth_client_id}
Client Secret: {secret.oauth_client_secret}
Scope:         api.read api.write

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.