# Notifier

mx-notifier is a blockchain event streaming service that sits between the MultiversX node and downstream consumers. It receives raw block data from the node over a binary protobuf WebSocket connection, normalizes that data into structured events, and fans them out to configured subscribers.

***

## Architecture position

```
MultiversX Node
    │  binary protobuf WebSocket frames
    ▼
mx-notifier
    ├── /hub/ws ──────► mx-relayer (internal WebSocket consumer)
    ├── RabbitMQ ──────► enterprise message queue consumers
    └── Azure Service Bus ► cloud messaging consumers
```

The node pushes block data to mx-notifier over a persistent WebSocket connection using binary protobuf frames. mx-notifier decodes each frame, preprocesses the payload, and delivers normalized events to all active output channels simultaneously.

mx-relayer connects to the `/hub/ws` endpoint to receive account delta and transaction status updates, then fans them out to its own WebSocket clients. See the [Relayer WebSocket API](/developers/relayer-api.md) for details on that layer.

***

## Modes of consumption

### Hub WebSocket (`/hub/ws`)

The hub WebSocket is an internal endpoint intended for trusted service consumers in the same infrastructure boundary. Consumers connect, send a `SubscribeEvent` protobuf message to declare their filter criteria, and receive a stream of matching events in the same binary protobuf framing format used by the node.

Use the hub WebSocket when:

* You need sub-second event delivery with minimal additional infrastructure
* You are operating a service within the same network as mx-notifier (e.g., mx-relayer)
* You need fine-grained subscription filtering by address, identifier, or topic prefix

### Message brokers (RabbitMQ / Azure Service Bus)

Events are also published to external message brokers for integration with broader data pipelines. These channels add durable delivery, replay, and fan-out for asynchronous or batch processing workloads.

Use a message broker when:

* Consumers need durable message storage and guaranteed delivery
* You are integrating with existing AMQP or Azure Service Bus infrastructure
* You require ordered delivery across multiple consumer instances
* Consumers cannot maintain a persistent WebSocket connection

***

## Documentation structure

| Page                                                      | Contents                                                                |
| --------------------------------------------------------- | ----------------------------------------------------------------------- |
| [connection.md](/developers/notifier/connection.md)       | Hub WebSocket protocol, frame format, acknowledgement, backpressure     |
| [topics.md](/developers/notifier/topics.md)               | All 8 topics received from the MX node — payloads, timing, use cases    |
| [filtering.md](/developers/notifier/filtering.md)         | Subscription match levels, topic prefix matching, code examples         |
| [event-schemas.md](/developers/notifier/event-schemas.md) | NormalizedEvent structure, field reference, per-event-type topic layout |
| [publishers.md](/developers/notifier/publishers.md)       | RabbitMQ and Azure Service Bus configuration and message format         |

***

## Key properties

| Property              | Detail                                                        |
| --------------------- | ------------------------------------------------------------- |
| Inbound protocol      | Binary protobuf WebSocket (`WsMessage` schema)                |
| Outbound hub protocol | Same binary protobuf WebSocket                                |
| Event deduplication   | Optional Redis-backed cache, configurable TTL (default 300 s) |
| Resilience            | Circuit breaker, retry queue, auto-reconnect to node          |
| Supported brokers     | RabbitMQ (AMQP), Azure Service Bus                            |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xoxno.com/developers/notifier.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.