Headers exchange in RabbitMQ - Commands & Configuration

Introduction

Sometimes you want to send messages to queues based on multiple message properties instead of just a simple name. Headers exchange lets you route messages by matching key-value pairs in message headers, giving you flexible control over where messages go.

When you want to route messages based on multiple attributes like type, format, or priority.

When routing rules need to match several header values instead of just one routing key.

When you want to decouple routing logic from routing keys and use message metadata instead.

When you have complex filtering needs that cannot be handled by direct or topic exchanges.

When you want to support flexible message routing without changing routing keys in the producer.

Config File - headers_exchange_setup.sh

headers_exchange_setup.sh

#!/bin/bash

# Create a headers exchange named 'my_headers_exchange'
rabbitmqadmin declare exchange name=my_headers_exchange type=headers

# Create a queue named 'my_queue'
rabbitmqadmin declare queue name=my_queue durable=true

# Bind the queue to the headers exchange with header matching arguments
rabbitmqadmin declare binding source=my_headers_exchange destination=my_queue arguments='{"x-match":"all", "format":"pdf", "type":"report"}'

This script creates a headers exchange called my_headers_exchange. It then creates a durable queue named my_queue. Finally, it binds the queue to the exchange with header matching rules that require all headers to match: format=pdf and type=report. Messages sent to this exchange with these headers will be routed to my_queue.

Commands

This command creates a new headers exchange named 'my_headers_exchange' where messages will be routed based on header values.

Terminal

rabbitmqadmin declare exchange name=my_headers_exchange type=headers

Expected Output

Exchange 'my_headers_exchange' declared

→

type=headers - Specifies the exchange type as headers for routing by message headers

This command creates a durable queue named 'my_queue' that will receive messages matching the headers.

Terminal

rabbitmqadmin declare queue name=my_queue durable=true

Expected Output

Queue 'my_queue' declared

→

durable=true - Ensures the queue survives broker restarts

This command binds 'my_queue' to 'my_headers_exchange' with header matching rules requiring all headers to match: format=pdf and type=report.

Terminal

rabbitmqadmin declare binding source=my_headers_exchange destination=my_queue arguments='{"x-match":"all", "format":"pdf", "type":"report"}'

Expected Output

Binding from 'my_headers_exchange' to 'my_queue' declared

→

arguments - Defines header matching rules; 'x-match' can be 'all' or 'any'

This command sends a message with headers matching the binding rules, so it will be routed to 'my_queue'.

Terminal

rabbitmqadmin publish exchange=my_headers_exchange routing_key= headers='{"format":"pdf", "type":"report"}' payload='Monthly report PDF'

Expected Output

Message published

→

headers - Specifies message headers used for routing

This command retrieves the message from 'my_queue' to verify it was routed correctly.

Terminal

rabbitmqadmin get queue=my_queue requeue=false

Expected Output

Message 1:

{

  "payload": "Monthly report PDF",

  "headers": {

    "format": "pdf",

    "type": "report"

  }

}

→

requeue=false - Removes the message from the queue after retrieval

Key Concept

If you remember nothing else from this pattern, remember: headers exchanges route messages by matching key-value pairs in message headers, allowing flexible multi-attribute routing.

Common Mistakes

Using routing keys instead of headers with a headers exchange

Headers exchanges ignore routing keys and only use message headers for routing, so routing keys have no effect.

Set the routing criteria in message headers and binding arguments, not in routing keys.

Setting 'x-match' to 'all' but only providing some headers in the message

The message will not match the binding because all headers must match when 'x-match' is 'all'.

Ensure the message includes all headers specified in the binding or use 'x-match' set to 'any' for partial matches.

Not quoting JSON properly in binding arguments

Incorrect JSON syntax causes the binding command to fail or behave unexpectedly.

Use proper JSON syntax with escaped quotes when passing arguments in the command line.

Summary

Create a headers exchange to route messages based on header key-value pairs.

Create a queue and bind it to the exchange with header matching rules using 'x-match'.

Publish messages with headers matching the binding to route them to the correct queue.

Retrieve messages from the queue to verify correct routing.