Webhooks in Bot Forms

This article describes, how webhooks in forms work and how they are implemented.

General information

The use of the webhook feature enables the use of APIs and thus the retrieval and transmission of data. The feature can be used as an action in forms. If webhooks are used in forms, it is possible to transmit received data to another system or to carry out authentication.

All important settings are made on the webhook configuration page:

Specification of the target URL
Definition of the HTTP method (POST, GET, etc.)
Configuration of user-defined headers or body as JSON

Access to the dialog context is always possible via templates (handlebars), e.g. to transmit queried data such as customer numbers or other required information to the API. At the same time, it is possible to define various steps in the form, e.g. to check an entered customer number via a webhook. The result of the query is saved in the dialog context so that this information can be accessed in subsequent steps.

Webhook settings

In order to optimize communication with an API, several elements of the webhook can be configured:

Context name: The context name enables the webhook's response to be saved in the dialog context. The context can be used via handlebars, e.g. , is possible.
URL: The target URL of the webhook is specified here. It is the address of the API with which the webhook communicates. It can be an internal or external API.
Method: The HTTP method is the method used by the webhook to send the data. Common methods are POST (for transmitting data) and GET (for retrieving data). In some cases, other methods such as PUT or DELETE are also possible.
Headers: It is possible to add user-defined headers that are transmitted to the API during the request. A typical example is the X-Api key for authenticating the request. Any number of headers can be configured here to meet the requirements of the target API.
Body: There are various body options, such as Default or Custom. With the Custom option, it is possible to customize the body so that specific data can be sent to the API. This is particularly useful if more complex data structures need to be transferred. The body is configured in JSON format and contains the data that is to be transmitted to the API. Access to the dialog context is possible via handlebars in order to dynamically integrate information such as customer data or responses.
Authentication: If HTTP Basic authentication is required for the webhook, the user name and password can be specified. Alternatively, a token-based authentication system (e.g. Bearer Token) can also be used by setting corresponding headers.

Example: Transmission of the meter reading

A customer wants to transmit their meter reading to the electricity service provider. A form is used to request the relevant data. A webhook transmits the data to the backend.

Procedure:

Entry of customer data: The customer enters their customer number and date of birth. The date of birth serves as legitimization for the change in the backend. If the customer number does not match the date of birth, the process is canceled.
Authentication: The customer data is sent to the backend via an initial webhook endpoint “Auth” to check the customer's authorization. This step ensures that the data entered is correct and that the customer is authorized to make changes. Example of the webhook configuration:
- URL: https://api.stromdienstleister-xyz.de/v1/customer/authenticate
- Method: POST
- Context name: auth_response
- Headers:
```
{
  "X-Api-Key": "<Ihr-Api-Key>",

  "Content-Type": "application/json"

}
```
- Body:
```
{

  "customerNumber": "",

  "birthDate": ""

}
```
- Response: The backend returns a response indicating whether the customer has been authenticated. Example:
```
{

  "auth": true,

  "customerId": "123456",

  "message": "Authentication successful"

  "jwt": "the jwt token"

}
```
Enter meter reading: The customer enters the current meter reading and submits the form.
- JWT for authentication: In addition to the API key, a JWT (JSON Web Token) can be used for authentication. The JWT is added in the header as Authorization and ensures that the request comes from an authorized user.
  Access is via the context name defined in the previous webhook.
- URL: https://api.stromdienstleister-xyz.de/v1/customer/update
- Method: POST
- Context name: customer_update_response
- Headers:
```
{

 "Authorization": "Bearer ",

 "Content-Type": "application/json" 

}
```
- Body:
```
{

  "customerNumber": "",

  "updateType": "meterReading",

  "value": ""

}
```
- Response (Example):
```
{

  "status": "success",

  "updateId": "78910",

  "message": "Update successfully processed"

}
```
Confirmation and validation: The backend validates the entries again and sends a confirmation to the customer if necessary.

Security and protection against misuse (recommendation):

API key and JWT: The use of an API key in combination with a JWT provides an additional layer of security. The API key is sent in the header, while the JWT ensures that the request is authenticated and takes place within a certain period of time.
TLS/SSL encryption: All data transfers should be made via HTTPS to ensure that the data is encrypted during transmission and cannot be intercepted by third parties.

This example shows how flexibly webhooks can be used in our platform to meet customer-specific requirements and communicate with existing systems. The use of handlebars makes it possible to access information dynamically and integrate it efficiently into the webhook requests.

If you have any further questions about using the webhook feature or configuration, please contact our Customer Success Team.