Skip to main content

RabbitMQ transport (legacy)

Prefer WebSocket for new integrations

RabbitMQ/AMQP is fully supported but is the legacy notification transport. New integrations should use the WebSocket tunnel, which needs only port 443 and no extra firewall rules. This page is for existing deployments and networks where AMQP is already established.

BranchKey can deliver aggregation notifications over an AMQP (RabbitMQ) connection instead of the WebSocket tunnel. Functionally it is equivalent — you still read notifications from client.queue — but it requires an additional outbound port.

Enabling it​

RabbitMQ is selected by leaving use_websocket unset or False:

from branchkey import Client, Credentials, APIConfig, RabbitMQConfig

client = Client(
    credentials=credentials,
    api_config=APIConfig(host="https://app.branchkey.com"),
    rabbitmq_config=RabbitMQConfig(
        host=None,     # auto-derived from the API host if left as None
        port=5671,     # AMQPS (TLS) — the required production port
        ssl=True,      # TLS is mandatory in production
    ),
    use_websocket=False,
)

aggregation_id = client.queue.get(block=True, timeout=300)
client.file_download(aggregation_id)

TLS is required​

As of the January 2026 TLS migration, the BranchKey RabbitMQ endpoint requires encrypted connections:

  • Host: rabbitmq.branchkey.com (auto-derived from your API host if host=None)
  • Port: 5671 (AMQPS / TLS). The old plaintext port 5672 is for local development only.
  • TLS: ssl=True (default). The client validates the server certificate against your system CA store (BranchKey uses Let's Encrypt certificates).

If certificate verification fails on an older system, update your CA bundle:

# Debian / Ubuntu
sudo apt-get update && sudo apt-get install ca-certificates

Firewall requirements​

DirectionDestinationPortProtocol
Outboundapp.branchkey.com443HTTPS (REST API — always required)
Outboundrabbitmq.branchkey.com5671AMQPS (TLS)

The extra outbound 5671 requirement is the main operational reason to prefer the WebSocket transport, which reuses the 443 connection you already have.

Configuring reconnection​

from branchkey import Client, RabbitMQConfig

client = Client(
    credentials=credentials,
    rabbitmq_config=RabbitMQConfig(
        port=5671,
        ssl=True,
        max_reconnect_attempts=0,      # 0 = retry forever (default)
        reconnect_backoff_factor=2.0,
        reconnect_max_delay=60,
    ),
)

Local development​

For a local stack you may use plaintext AMQP — never in production:

client = Client(
    credentials=credentials,
    api_config=APIConfig(host="http://127.0.0.1", ssl=False),
    rabbitmq_config=RabbitMQConfig(host="127.0.0.1", port=5672, ssl=False),
    use_websocket=False,
)

See also​