Listeners

What is a Listener?

A Listener is a foundational component of bots on the platform, designed to receive data from external applications and trigger automation workflows. By creating a Listener, you can provide an endpoint URL for external applications to call, enabling seamless integration without requiring any coding. Listeners require no additional integrations and can be set up directly within the platform.

In essence, a Listener is a webhook URL that acts as an endpoint, receiving data from third-party applications and triggering relevant automation actions.

How to Create a Listener

Follow these steps to set up a Listener:

• Log in to your autobotAI account.

• Navigate to Bot Building Blocks and click on Listeners.

• Click on the + New option to create a new Listener.

• Select the appropriate authentication method for the listener and provide the required and optional details as applicable.

  1. For an overview of supported authentication methods, refer to: Supported Webhook Authentication Types.

• Click Next, where you will see the generated Listener URL and Secret.

  1. ⚠️ Treat both the Listener URL and Secret as sensitive information.
     1. Do not share them publicly.
     2. Store them securely to prevent unauthorized access.

---

Supported Webhook Authentication Types

This section explains the various authentication methods available for webhooks and which platforms might use them.

1. Secret Key in Header

This method uses a secret key passed in the x-secret-key header for authentication.

🔹 Commonly Used By: General API integrations such as AWS EventBridge and other services that support custom headers

How It Works:

1. The webhook provider sends the request with the x-secret-key in the headers.
2. The listener validates the request by checking if the provided secret matches the configured secret.

Setup Requirements

What You Need to Set Up in autobotAI:

1. Define a Webhook Name and Webhook Description.
2. (Optional) Define Payload Validation Fields to enforce additional payload checks.

What You Need to Configure at the Webhook Provider:

1. Set the Listener URL as the destination for webhook events.
2. Include the x-secret-key header in webhook requests, matching the secret key configured in autobotAI.

2. Signature Verification

This method verifies incoming requests using HMAC-based signature verification.

🔹 Commonly Used By: Platforms like GitHub, GitGuardian, Twilio.

How It Works:

1. The webhook provider generates an HMAC signature using a secret key and includes it in the request header.
2. The listener recalculates the signature and verifies if it matches the received one.

Setup Requirements

What You Need to Set Up in autobotAI:

1. Define a Webhook Name and Webhook Description.
2. Provide a Signature Header (e.g., X-Hub-Signature-256 for GitHub).
3. Select the Signature Encoding Method:
   1. Hex (commonly used. e.g, GitHub, GitGuardian, etc.).
   2. Base64 (less common).
4. Define the Signature Prefix (e.g., sha256= for GitHub).
5. (Optional) Specify Additional Headers if required (e.g., timestamp for GitGuardian).
6. (Optional) Define Payload Validation Fields for additional security.

What You Need to Configure at the Webhook Provider:

1. Set the Listener URL as the webhook destination.
2. Configure the Secret Key for HMAC signature generation.

3. Secret Key in Query Parameters

This method authenticates requests by checking a secret key passed in the URL query parameters.

🔹 Commonly Used By: Webhook providers that do not support custom headers.

How It Works:

1. The webhook provider appends the secret key to the request URL.
2. The listener extracts and validates the secret from the query parameters.

Setup Requirements

What You Need to Set Up in autobotAI:

1. Define a Webhook Name and Webhook Description.
2. (Optional) Define Payload Validation Fields for additional security.

What You Need to Configure at the Webhook Provider:

1. Set the Listener URL as the webhook destination.

---

Testing a Listener

A Listener is automatically considered active and tested once it has received at least one call. Many webhook providers, such as GitHub, send an initial test message when a webhook is created to ensure the setup is correct. Additionally, you can manually trigger a test webhook from providers like GitGuardian or use tools like Postman to send sample data.

Manually Testing a Listener

1. Send a request using Postman or any API testing tool with a sample webhook payload.

Viewing Listener Events

To view the events received by a Listener:

• Go to the Listener page.
• Click Action next to the specific Listener.
• Select Test to view the events.

This will display the latest webhook events received by the Listener, showing the fields present in the most recent webhook call.

By following these steps, you can easily create, test, and manage Listeners in the platform to enable efficient data flow and automation.