Install events-into-rabbitmq plugin into headless wallet

Goal

This article will guide you to install the events-into-rabbitmq plugin into Hathor headless wallet.

The events-into-rabbitmq plugin is part of the external notification feature: it forwards wallet events — such as new transactions and balance updates for the wallets the headless instance manages — to a RabbitMQ queue, where your own services can consume them. For more on this feature and the full event payload, see Hathor external notifications.

Requirements

• Hathor headless wallet $\ge$ v0.41.0
• A running, reachable RabbitMQ instance and the name of the queue to publish to. The connection URL uses the AMQP scheme, for example amqp://user:password@localhost:5672. See the RabbitMQ download and installation guide.

Plugin configuration parameters

Source code flag	Docker Compose env var	Required	Example
--plugin_rabbitmq_queue	HEADLESS_PLUGIN_RABBITMQ_QUEUE	Yes	hathor-events
--plugin_rabbitmq_url	HEADLESS_PLUGIN_RABBITMQ_URL	Yes	amqp://user:password@localhost:5672

Step-by-step

1. Install dependency.
2. Configure and enable the plugin.

Step 1: install dependency

Source code

1. Open the command line from the directory where you installed Hathor headless wallet.
2. Run the command to install the dependencies:

npm install amqplib@^0.10.3

Docker container

If you installed Hathor headless wallet as a Docker container, you must build a new Docker image, with the installed dependencies. The image that Hathor Labs provides at Docker Hub does not come with the installed dependencies for this plugin:

1. Open the command line from the directory where you installed Hathor headless wallet.
2. Create a new empty Dockerfile file and write in it just the following lines:

Dockerfile

FROM hathornetwork/hathor-wallet-headless

RUN npm install amqplib@^0.10.3

3. Build a new Docker image, based on the Dockerfile you created in the previous substep, tagging it so you can reference it by name later:

docker build --tag hathor-wallet-headless-rabbitmq --file Dockerfile .

At the end of this step, you will have built a new Docker image tagged hathor-wallet-headless-rabbitmq. Use this tag in place of <docker_image_id> in the following steps.

Docker compose

If you installed Hathor headless wallet along Hathor full node with Docker compose, you must build a new Docker image, with the installed dependencies. The image that Hathor Labs provides at Docker Hub does not come with the installed dependencies for this plugin:

1. Open the command line from the directory where you installed Hathor headless wallet.
2. Create a new empty Dockerfile file and write in it just the following lines:

Dockerfile

FROM hathornetwork/hathor-wallet-headless

RUN npm install amqplib@^0.10.3

3. Build a new Docker image, based on the Dockerfile you created in the previous substep, tagging it so you can reference it by name later:

docker build --tag hathor-wallet-headless-rabbitmq --file Dockerfile .

At the end of this step, you will have built a new Docker image tagged hathor-wallet-headless-rabbitmq. Use this tag in place of <docker_image_id> in the following steps.

Step 2: configure and enable the plugin

:::warning Protect your seed phrase

The examples below show --seed_default / HEADLESS_SEED_DEFAULT inline for clarity. A seed phrase passed as a CLI argument or a plain environment variable can be exposed in shell history, docker inspect output, and process listings. For production, inject the seed at runtime via a secrets manager (Docker secrets or an environment file with restricted permissions) rather than hardcoding it.

:::

Source code

If you installed Hathor headless wallet from source code, you must modify both the src/config.js file and the command to start the application, to respectively enable and configure the plugin:

1. Open the command line from the directory where you installed Hathor headless wallet.
2. Open the src/config.js file.
3. Add 'rabbitmq' to the array of values of the enabled_plugins property to enable the plugin.

If you are enabling multiple plugins, value shall be an array of plugin ids: enabled_plugins: ['PluginId1', 'PluginId2', ...].

At the end of this substep, the config.js file will be as follows:

hathor-wallet-headless/src/config.js

module.exports = {

  ...

  enabled_plugins: ['rabbitmq'],

  plugin_config: {},

  ...

};

4. Append the --plugin_rabbitmq_queue <queue_name> parameter into the command to start the wallet application, replacing the <queue_name> placeholder with the RabbitMQ queue name.

5. Append the --plugin_rabbitmq_url <queue_url> parameter into the command to start the wallet application, replacing the <queue_url> placeholder with the RabbitMQ queue URL.

At the end of this substep, the command to start the wallet application will be as follows:

npm start -- --plugin_rabbitmq_queue <queue_name> --plugin_rabbitmq_url <queue_url>

Docker container

If you installed Hathor headless wallet as a Docker container, you must add parameters to the docker run command to enable and configure the plugin:

1. Append --enabled_plugins='rabbitmq' to the docker run command.

If you are enabling multiple plugins, parameter value shall be an array of plugin ids: --enabled_plugins='PluginId1 PluginId2 ...'.

2. Append --plugin_rabbitmq_queue=<queue_name>, replacing the <queue_name> placeholder with the RabbitMQ queue name.

3. Append --plugin_rabbitmq_url=<queue_url>, replacing the <queue_url> placeholder with the URL of the RabbitMQ queue URL.

4. Use the Docker image you built in the previous step, replacing the <docker_image_id> placeholder with its image id.

At the end of this step, the command to start the wallet application will be as follows:

docker run \
  -it -p 8000:8000 \
  <docker_image_id> \
  --seed_default '<24_words_seed_phrase_string>' \
  --network mainnet \
  --server https://node2.mainnet.hathor.network/v1a/ \
  --enabled_plugins='rabbitmq' \
  --plugin_rabbitmq_queue=<queue_name> \
  --plugin_rabbitmq_url=<queue_url>

Docker compose

If you installed Hathor headless wallet along Hathor full node with Docker compose, you must add new lines to the docker-compose.yml file to enable and configure the plugin:

1. Open the command line from the directory where you installed Hathor headless wallet.
2. Open the docker-compose.yml file.
3. At the end of the list of items within environment, from hathor-wallet-headless, add the key/value pair HEADLESS_ENABLED_PLUGINS=rabbitmq.

If you are enabling multiple plugins, value shall be an array of plugin ids: HEADLESS_ENABLED_PLUGINS=PluginId1 PluginId2.

4. At the end of the list of items within environment, from hathor-wallet-headless, add the key/value pair HEADLESS_PLUGIN_RABBITMQ_QUEUE=<queue_name>, replacing the <queue_name> placeholder with the RabbitMQ queue name.

5. At the end of the list of items within environment, from hathor-wallet-headless, add the key/value pair HEADLESS_PLUGIN_RABBITMQ_URL=<queue_url>, replacing the <queue_url> placeholder with the URL of the RabbitMQ queue URL.

6. Use the Docker image you built in the previous step, replacing the <docker_image_id> placeholder with its image id, as the value of the image key within hathor-wallet-headless.

At the end of this step, the docker-compose.yml file will be as follows:

docker-compose.yml

hathor-core:
  ...
hathor-wallet-headless:
  image: <docker_image_id>
  ...
  environment:
    - HEADLESS_SEED_DEFAULT=<24_words_seed_phrase_string>
    - HEADLESS_NETWORK=testnet
    - HEADLESS_SERVER=http://hathor-core:8080/v1a/
    - HEADLESS_ENABLED_PLUGINS=rabbitmq
    - HEADLESS_PLUGIN_RABBITMQ_QUEUE=<queue_name>
    - HEADLESS_PLUGIN_RABBITMQ_URL=<queue_url>

Verify the plugin is active

After starting the wallet with the plugin enabled:

1. Check the startup logs. The wallet logs that the rabbitmq plugin was loaded during initialization. A connection error logged here usually means the AMQP URL is wrong or RabbitMQ is unreachable.
2. Trigger an event. Send a transaction to one of the wallets the headless instance manages (see Send a transfer).
3. Confirm delivery. In the RabbitMQ management UI (or via rabbitmqadmin), open your queue and confirm the message count increased.

Troubleshooting

• ECONNREFUSED / connection refused at startup. RabbitMQ is not reachable at the URL provided. Confirm the instance is running and the host, port, and credentials in --plugin_rabbitmq_url are correct.
• Plugin not loaded. Confirm rabbitmq is present in enabled_plugins (source code) or HEADLESS_ENABLED_PLUGINS (Docker), and that you started the wallet from the image you rebuilt with amqplib installed — not the stock Docker Hub image.
• Wallet starts but no messages arrive. Verify the queue name matches exactly, and that events are actually occurring on a managed wallet (send a test transaction to confirm).

Task completed

You have installed the events-into-rabbitmq plugin in your instance of Hathor headless wallet.

The events-into-rabbitmq plugin is part of the external notification feature. For how to use this plugin or install other plugins of this feature, see Hathor external notifications.