Add a Custom Extension Listener to WSO2 API Manager.

Photo by Alexey Demidov on Unsplash

In WSO2 API Manager, Extension Listeners provide a powerful mechanism to intercept and control the flow of requests and responses within the API Gateway. They can be used to enrich payloads, apply custom validations, manage caching strategies, or enable additional monitoring.

For WSO2 API Manager you can also create your own custom implementation to meet specific requirements. This guide walks you through the steps I followed when adding a custom Extension Listener in WSO2 API Manager 4.2.0.

You can find the complete implementation in my GitHub repository: custom-extension-listner

Step 1: Implement the ExtensionListener Interface

Create a custom class that implements the ExtensionListener interface. This interface exposes the lifecycle methods needed to hook into request and response flows.

In your implementation, you can define custom logic for interception, enrichment, or validation. For example, in my project, the class org.example.apim.extensions.CustomErrorExtensionListener demonstrates how to extend the default authentication flow by handling errors in a custom way.

Step 2: Package the Project as an OSGi Bundle

You can deploy this listener within WSO2 API Manager, either as a non OSGI jar placed inside the lib directory or as an OSGI bundle inside the <API-M_HOME>/repository/components/dropins directory. Here, I’m going to package it as an OSGi-compatible bundle. This ensures that the JAR can be loaded by the OSGi runtime inside API Manager.

You can achieve this by configuring your pom.xml with the necessary OSGi plugin settings. Once configured, run the Maven build to generate the JAR.

For reference, see the [pom.xml](https://github.com/RusJaI/custom-extension-listner/blob/main/pom.xml) file in my GitHub repository, which is already set up for creating an OSGi bundle.

After a successful build, you will get the JAR file inside the target/ directory. This JAR is what you’ll deploy into API Manager in the next step.

Step 3: Update the deployment.toml

Add the following configuration to the deployment.toml file of API Manager to register your custom listener:

[[apim.extension.listener]]
type  = "AUTHENTICATION"
class = "org.example.apim.extensions.CustomErrorExtensionListener"

Here:

• type specifies the category of listener (e.g., AUTHENTICATION, TRAFFIC, etc.).
• class should point to the fully qualified class name of your implementation.

Step 4: Deploy and Test

1. Copy the generated JAR into the <APIM_HOME>/repository/components/dropins directory.
2. Start the WSO2 API Manager server.
3. Invoke an API to confirm that your custom listener is triggered as expected.

With these steps, you can extend the API Gateway’s behavior and tailor it to your specific requirements.

See you!