Install events-into-amazon-sqs plugin into headless wallet

Goal

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

The events-into-amazon-sqs 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 an Amazon SQS 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
• An existing Amazon SQS queue and its URL.
• Valid AWS credentials available in the environment where the wallet runs. The aws-sdk resolves credentials from the standard chain — AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY environment variables, a shared credentials file, or an IAM role (for EC2/ECS/EKS). The IAM identity must have sqs:SendMessage permission on the target queue. See Configuring the AWS SDK for JavaScript.

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 dependency:

npm install aws-sdk@^2.1226.0

Docker container

If you installed Hathor headless wallet as a Docker container, you must build a new Docker image, with all installed dependencies. The image that Hathor Labs provides at Docker Hub does not come with all dependencies installed 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 aws-sdk@^2.1226.0

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-sqs --file Dockerfile .

At the end of this step, you will have built a new Docker image tagged hathor-wallet-headless-sqs. 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 aws-sdk@^2.1226.0

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-sqs --file Dockerfile .

At the end of this step, you will have built a new Docker image tagged hathor-wallet-headless-sqs. 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 (AWS 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 'sqs' 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: ['sqs'],

  plugin_config: {},

  ...

};

4. Append the --plugin_sqs_region <aws_region> parameter into the command to start the wallet application, replacing the <aws_region> placeholder with the AWS region code of the Amazon SQS.

5. Append the --plugin_sqs_queue_url <queue_url> parameter into the command to start the wallet application, replacing the <queue_url> placeholder with the URL of the Amazon SQS queue.

6. (Optional) When developing, you may want to run a local queue. In this case, do this substep to point the aws-sdk to a local instance. Append the --plugin_sqs_endpoint_url <endpoint_url> parameter, replacing the <endpoint_url> placeholder with the endpoint of your local queue instance.

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

npm start -- --plugin_sqs_region <aws_region> --plugin_sqs_queue_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='sqs' 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_sqs_region=<aws_region>, replacing the <aws_region> placeholder with the AWS region code of the Amazon SQS.

3. Append --plugin_sqs_queue_url=<queue_url>, replacing the <queue_url> placeholder with the URL of the Amazon SQS queue.

4. (Optional) When developing, you may want to run a local queue. In this case, do this substep to point the aws-sdk to a local instance. Append the --plugin_sqs_endpoint_url=<endpoint_url> parameter, replacing the <endpoint_url> placeholder with the endpoint of your local queue instance.

5. 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='sqs' \
  --plugin_sqs_region=<aws_region> \
  --plugin_sqs_queue_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=sqs.

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_SQS_REGION=<aws_region>, replacing the <aws_region> placeholder with the AWS region code of the Amazon SQS.

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

6. (Optional) When developing, you may want to run a local queue. In this case, do this substep to point the aws-sdk to a local instance. At the end of the list of items within environment, from hathor-wallet-headless, add the key/value pair HEADLESS_PLUGIN_SQS_ENDPOINT_URL=<endpoint_url>, replacing the <endpoint_url> placeholder with the endpoint of your local queue instance.

7. 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=sqs
    - HEADLESS_PLUGIN_SQS_REGION=<aws_region>
    - HEADLESS_PLUGIN_SQS_QUEUE_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 sqs plugin was loaded during initialization. If AWS credentials are missing or invalid, the plugin logs an authentication error here — this is the most common failure point.
2. Trigger an event. Send a transaction to one of the wallets the headless instance manages (see Send a transfer).
3. Confirm delivery. Check that a message arrived in the queue, for example with the AWS CLI:

aws sqs receive-message --region <aws_region> --queue-url <queue_url>

If no message arrives, verify the IAM identity has sqs:SendMessage on the queue and that the region and queue URL match.

Task completed

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

The events-into-amazon-sqs 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.