External Notifications

External notifications allow integrated systems to receive real-time updates from Hathor headless wallet without continuously polling the API.

They are useful for applications that need to react to wallet, transaction, node, or blockchain state changes. For example, an application can be notified when a wallet becomes ready, when a new transaction arrives, or when the node connection state changes.

Overview

External notifications are delivered through plugins installed in Hathor headless wallet.

Each plugin receives events emitted by the headless wallet and forwards them to an external destination, such as:

• Standard output
• WebSocket clients
• Amazon SQS
• RabbitMQ
• A custom destination implemented by your team

This allows your application to subscribe to important events and react to them asynchronously.

Why use external notifications?

Many applications need to perform actions when something changes in Hathor, such as:

• A wallet finishes syncing and becomes ready to use.
• A wallet receives a new transaction.
• A transaction in the wallet history is updated.
• The connection between the headless wallet and the Hathor network changes.
• A new block is found in the best chain.

Without external notifications, your system would need to poll Hathor headless wallet repeatedly.

For example, to detect new wallet transactions, your application might need to request the wallet transaction history every few seconds, compare the latest response with the previous one, and identify any new transactions manually.

With external notifications, Hathor headless wallet sends an event whenever a relevant state change happens. Your application can then process the event immediately, without maintaining a polling loop.

How it works

External notifications follow an event-driven model.

Hathor headless wallet emits events when relevant changes happen in the wallet, node connection, or blockchain state. Installed notification plugins receive those events and forward them to external systems.

Credits: wallet icon created by James Kopina from the Noun Project.

A typical setup works like this:

1. Your system starts one or more wallets in Hathor headless wallet.
2. Hathor headless wallet monitors wallet, node, and blockchain state changes.
3. An external notification plugin receives emitted events.
4. The plugin forwards those events to an external destination.
5. Your application consumes the events and reacts to them.

For example, one plugin can send events to a WebSocket client, another can send events to an Amazon SQS queue, and a custom plugin can forward events to an internal monitoring service.

Supported events

Hathor headless wallet can emit the following external notification events:

Event	Description	Common use case
wallet:state-changed	Emitted when a wallet state changes.	Detect when a wallet is ready, syncing, closed, or in an error state.
wallet:new-tx	Emitted when a new transaction arrives in a wallet.	React to incoming transactions without polling wallet history.
wallet:update-tx	Emitted when a transaction in the wallet history is updated.	Detect spent UTXOs, transaction status changes, or voided transactions.
node:state-changed	Emitted when the headless wallet connection state changes.	Monitor availability of the connection to the Hathor network.
node:wallet-update	Internal event used by Hathor headless wallet to generate wallet-related events.	Usually not consumed directly by integrated systems.
node:best-block-update	Emitted when the best blockchain height changes.	Detect when a new block is found in the best chain.
wallet:load-partial-update	Emitted while a wallet history is being loaded.	Track wallet loading or syncing progress.

Event details

wallet:state-changed

The wallet:state-changed event is emitted when the state of a wallet started in Hathor headless wallet changes.

Possible wallet states include:

• Closed
• Connecting
• Syncing
• Ready
• Error
• Processing

This event is useful when your application needs to know whether a wallet can already be used.

For example, after starting a wallet, your application can wait for the wallet to reach the Ready state before enabling transaction-related operations.

It can also be used for monitoring. If a wallet moves from Ready to Error, your application can trigger alerts, retry logic, or fallback behavior.

wallet:new-tx

The wallet:new-tx event is emitted when a new transaction arrives in a wallet.

This event is useful for systems that need to react to incoming funds, token transfers, NFT activity, or any transaction involving a monitored wallet.

Instead of repeatedly checking the wallet transaction history, your application can listen for this event and process the new transaction when it arrives.

wallet:update-tx

The wallet:update-tx event is emitted when a transaction already present in the wallet history is updated.

This can happen when:

• A UTXO is spent.
• A transaction status changes.
• A previously valid transaction becomes voided because of a blockchain reorganization.

This event is important for applications that rely on transaction status. Your system should not only listen for new transactions, but also for updates to existing ones.

node:state-changed

The node:state-changed event is emitted when the connection state between Hathor headless wallet and the Hathor network changes.

Possible node connection states include:

• Closed
• Connecting
• Connected

This event helps integrated systems monitor network availability.

For example, if the node state changes to Closed, your system can pause transaction submission, notify operators, or switch to degraded behavior until the connection is restored.

node:wallet-update

The node:wallet-update event is used internally by Hathor headless wallet to generate wallet-related events.

Most integrated systems do not need to consume this event directly. In most cases, applications should consume higher-level wallet events such as:

• wallet:state-changed
• wallet:new-tx
• wallet:update-tx
• wallet:load-partial-update

node:best-block-update

The node:best-block-update event is emitted when the best blockchain height changes.

This usually means a new block was found in the best chain.

Applications can use this event to monitor blockchain progress, update block-related metrics, or trigger processes that depend on new block confirmations.

wallet:load-partial-update

The wallet:load-partial-update event is emitted while Hathor headless wallet is loading a wallet history from the blockchain.

This event is useful when your application needs to show or track wallet loading progress.

For example, after starting a wallet, your application can use this event to display sync progress before the wallet reaches the Ready state.

Available Plugins

To use external notifications, install one of the official external notification plugins.

Hathor currently provides plugins for the following destinations:

Plugin	Destination	Recommended use
Events into stdout	Standard output	Local development, debugging, and testing.
Events into WebSocket	WebSocket clients	Real-time applications and browser-based integrations.
Events into Amazon SQS	Amazon SQS queue	Cloud-based asynchronous processing.
Events into RabbitMQ	RabbitMQ queue	Message-driven systems using RabbitMQ.

Events into stdout

The stdout plugin sends all events to the standard output stream.

Use this plugin when developing, debugging, or inspecting the events emitted by Hathor headless wallet.

To install this plugin, see:

How to install the events-into-stdout plugin

Events into WebSocket

The WebSocket plugin starts a WebSocket server and sends events to connected WebSocket clients.

Use this plugin when your application needs to receive real-time updates directly through a WebSocket connection.

To install this plugin, see:

How to install the events-into-websocket plugin

Events into Amazon SQS

The Amazon SQS plugin sends events to an Amazon SQS queue.

Use this plugin when your application runs on AWS or when you need durable, asynchronous processing of wallet and node events.

To install this plugin, see:

How to install the events-into-amazon-sqs plugin

Events into RabbitMQ

The RabbitMQ plugin sends events to a RabbitMQ queue.

Use this plugin when your system already uses RabbitMQ or when you need to route Hathor events through a message broker.

To install this plugin, see:

How to install the events-into-rabbitmq plugin

Creating Custom Plugins

The official plugins cover common integration needs. However, some applications may need to send external notifications to a different destination, apply custom transformation logic, or integrate with internal infrastructure.

In those cases, you can create a custom external notification plugin for Hathor headless wallet.

For more information, see:

Creating an external notification custom plugin for Hathor headless wallet

Recommended Integration Flow

A typical integration can follow this flow:

1. Install and configure the notification plugin that matches your infrastructure.
2. Start Hathor headless wallet with the plugin enabled.
3. Start or load the wallets used by your application.
4. Listen for wallet:load-partial-update and wallet:state-changed events.
5. Wait until the wallet reaches the Ready state.
6. Process wallet:new-tx events for incoming transactions.
7. Process wallet:update-tx events to keep transaction state synchronized.
8. Monitor node:state-changed events for availability and operational health.
9. Optionally monitor node:best-block-update events for blockchain progress.

Key Takeaways

• External notifications allow integrated systems to receive Hathor events without polling.
• Notifications are emitted by Hathor headless wallet and delivered through plugins.
• Applications can listen for wallet, transaction, node, and blockchain events.
• wallet:new-tx helps applications react to incoming transactions.
• wallet:update-tx helps applications keep transaction state synchronized.
• wallet:state-changed and node:state-changed are useful for readiness checks and monitoring.
• Official plugins are available for stdout, WebSocket, Amazon SQS, and RabbitMQ.
• Custom plugins can be created for use cases that require different destinations or custom processing.