Skip to main content

Creating an external notification custom plugin


This article is the reference material for developers who want to create their own custom plugin to enhance the external notifications feature of Hathor headless wallet.


External notification is a feature available on Hathor headless wallet through the installation of plugins. At the moment, Hathor has four official plugins that cover the most basic needs. Nevertheless, some use cases may have specific not covered needs. In this situation, the use cases can create their own custom external notifications plugins. This article provides all prescriptions that a use case needs to develop such a plugin.

To know more about the external notifications feature, see About external notifications.


  • You should be familiar with the events module of Node.js, specifically, the EventEmitter class.
  • We advise you to develop the plugin to run Hathor headless wallet using Docker rather than from source code.

All prescriptions in this article assume the installation of Hathor headless wallet as a Docker container.

  • The only file you shall modify in Hathor headless wallet is Dockerfile.
  • In the Hathor headless wallet project, you must add the developed plugin module to hathor-wallet-headless/src/plugins directory.
  • In the Dockerfile, you must append the following:

FROM hathornetwork/hathor-wallet-headless

RUN npm install <required-dependency-nr1> <required-dependency-nr2>

COPY ./<custom_plugin.js> ./src/plugins/<custom_plugin.js>

  • Note that in the command to install the dependencies you must replace the <required-dependency-nrx> placeholders with the plugin dependencies.
  • In the command to copy the plugin, you must replace the <custom_plugin.js> placeholder with the file name of the plugin module.
  • All the plugin source code shall be at the <custom_plugin.js> module.
  • <custom_plugin.js> must export an async init method that receives an EventEmitter object. The EventEmitter receives all events generated by the application.
  • In case you are running Hathor headless wallet as a container alone, append the parameters --plugin_<pluginId>_name and --plugin_<pluginId>_file, replacing the <pluginId> placeholder with the string you chose to be the plugin id, to the run Docker command.
  • Now, in case you are running Hathor headless wallet with Docker compose, add the environment variables HEADLESS_PLUGIN_<pluginId>_NAME and HEADLESS_PLUGIN_<pluginId>_FILE to the docker-compose.yml file.
  • Finally, we advise you to study the source code of one of our four official plugins — available at hathor-wallet-headless/src/plugins —, to understand the mechanics of such plugins, and use as a pastiche to your custom plugin.


About external notifications.

If you are interested in seeing the development process of external notifications in Hathor, you can see this pull request, where we added support to this feature in Hathor headless wallet.