Webhooks: Use and configuration

Webhooks enable real-time communication between different applications. In this process, one server (the sender) automatically sends an HTTP enquiry to another server (the recipient). In the context of moinAI, this means that data collected in the chat is transmitted to an external system, or information is retrieved from there, so that it can be displayed to users directly within the chat widget.

The prerequisites for using a webhook are an existing form or an AI agent in the Hub and an accessible target URL (API endpoint) for the external system.

1. Benefits and functionality

2. Create a webhook

   2.1 Technical configuration
   2.2 Advanced options (cookies & authentication)
   2.3 Webhook actions before execution

3. Use in chatbots
   3.1 Webhooks as AI actions
   3.2 Webhooks in forms

4. Testing and Validation

5. Practical Examples

1. Benefits and functionality

The use of webhooks allows the AI chatbot to be seamlessly integrated with third-party systems such as CRM tools, product databases and e-commerce platforms. This offers the following benefits:

• Automation: Processes such as booking appointments or checking order statuses take place directly within the conversation, enabling self-service interactions

• Flexibility: Any REST webhooks can be integrated without the need for code modifications.

• Contextual relevance: Information from the ongoing conversation is fed directly into the API query, e.g. customer status, current subpage or product interest.

2. Create webhook

1. You can access the overview in the Hub via the menu item Integrations → Webhooks (Push).
2. Click the Edit button to open the list of existing webhooks.
3. The Create webhook + button opens a new, blank form.
   
   
4. Existing webhooks can be customised using the pencil icon.
   
5. By clicking the Deploy button at the bottom/top right of the webhook editor, the webhook becomes available in both the preview and live environments and can be linked to AI agents or forms.

2.1 Technical Configuration

The basic settings for the interface are defined in the edit view.

1. Select a name: A custom name used for internal identification within the Hub. The name can be easily changed at any time.

2. Define context name: The API response is saved in the dialogue under this name. It is also possible to use the context name elsewhere as a reference, e.g. via handlebars. For this reason, the name should remain as consistent as possible, otherwise every link will require manual adjustment.

3. Enter target URL: The API address to which the data is sent. This can be an internal or external API. Handlebars can also be used here, so that the URL is not static but can be used dynamically.

4. Select method: Specify the HTTP method by which the webhook sends the data. By default, POST is used to send data and GET to retrieve it.

2.2 Optional: Advanced options (cookies & authentication)

For specialised requirements, the editor offers additional control options:

• Customise headers: Using the Add field option, you can define custom headers (e.g. content-type: application/json) to be sent with the enquiry to the API. Alternatively, you can load a standard set using the Template option. A typical example is the X-Api-Key for authenticating the enquiry. Here, any number of headers can be configured to meet the requirements of the target API.

• Body: The options are Default, Custom and No Body.

• • Default: Time-saving consolidation and transmission of all information from a conversation in a single package. Due to frequent data overload and incompatible formats, its use with POST methods is not recommended, as interfaces (APIs) require precise data structures.
  • No Body: This option is selected when no message content is required for the enquiry. This is the default for GET enquiries, where data is retrieved exclusively via the URL.
  • Custom: This option allows for customisation of the body, enabling specific data to be sent to the API. This is particularly useful when more complex data structures need to be transferred. The body is configured in JSON format. Using handlebars, information from the dialogue context can be specifically accessed to integrate dynamic information such as customer data or responses.

• Use of cookies: Enabling this option means that cookies in the webhook request are accepted and used by the target system. This is particularly important for maintaining sessions across webhook calls. From a data protection perspective, you should check whether this needs to be specifically mentioned in the privacy policy. More information on data protection is provided in this article.
• Authentication: Here, you can choose between No authentication (security is handled, for example, via an API key in the header) and Basic Auth (request for username and password). 

Security and protection against misuse (recommendation)

1. API key and JWT: Using an API key in combination with a JWT provides an additional layer of security. The API key is included in the header, whilst the JWT ensures that the enquiry is authenticated and made within a specific timeframe.

2. TLS/SSL encryption: All data transfers should be carried out via HTTPS to ensure that the data is encrypted during transmission and cannot be intercepted by third parties.

2.3 Webhook actions before execution

Optionally, actions can be enabled that are executed immediately before the webhook is sent:

• User Message History: Adds the conversation’s message history to date to the context. This is useful if the target system (e.g. a CRM) requires the full conversation context for further processing.

• Save File URL(s): Saves the URLs of files that users have previously uploaded in the chat to the context. This is essential for processes where documents or images need to be transferred to a backend.

3. Use in chatbot

Once a webhook has been configured, it can be used in various places within the chatbot.

3.1 Webhooks as AI Actions

AI actions enable the AI agent to initiate a query independently when required.

1. Go to Knowledge Base → RAG → and click Add Action + in the Actions & Follow-Up card to create a new action.

2. The link is established by selecting the previously created webhook under Choose tool.

3. Thanks to precise parameter descriptions, the AI agent knows which information (e.g. an ID) it needs to request in advance.

More information on AI actions can be found in this article.

3.2 Webhooks in forms

In forms, integration takes place at a fixed point in the query path.

1. In the form editor, click the plus icon at the desired location.

2. Select Webhook from the element bar.

3. Choose the desired webhook from the field that appears.

You can find more information about forms in this article.

4. Testing and Validation

To ensure correct functionality, each configuration should be tested.

1. Click the Test button in the top-right corner of the webhook editor to open the test environment.

2. Select a form for simulating the database.

3. Click Send test data triggers the enquiry and validates the API’s response.
   
   

4. You can also validate the function in the preview (for webhooks in forms) or in the AI Playground (for webhooks in AI actions). The AI Playground shows in detail how an AI action was executed.
   
   

5. Practical Examples

{
  "orderNumber": "{{order_number_input}}",
  "email": "{{email_input}}"
}

{{#if shopify_order_status_url}}

{{#if shopify_shopify_fulfillments}}

{{#if (eq shopify_status "pending")}}

Your order has been processed but has not yet been dispatched.{{/if}}
{{#if (eq shopify_status "open")}}

Your order has been dispatched.{{/if}}

{{#if (eq shopify_status "success")}}

Your order has been confirmed.{{/if}}

{{#if (eq shopify_status "cancelled")}}

Your order has been cancelled.{{/if}}

{{#if (eq shopify_status "error")}}

There was an error with the delivery.{{/if}}

{{#if (eq shopify_status "failure")}}

Something went wrong with the delivery.{{/if}}

{{else}}

Your order has not yet been dispatched.{{/if}}

{{else}}

There is currently no order matching your details. Please check your details again or check the order status page:{{/if}}

{{#if order_status_response.tracking_url}}Track shipment{{else}}Go to customer account{{/if}}

{{#if order_status_response.tracking_url}}{{order_status_response.tracking_url}}{{else}}https://yourshop.com/login{{/if}}