Migrate from RabbitMQ

If you are coming from RabbitMQ, you will find that npayload simplifies many patterns that require careful configuration in RabbitMQ. Exchange types, binding declarations, dead-letter exchange chains, and retry topologies all collapse into straightforward channel and subscription configurations. This guide maps your RabbitMQ knowledge to npayload and walks through a practical migration.

Concept mapping

Key differences

No exchange types to choose

RabbitMQ has four exchange types (direct, topic, fanout, headers), each with different routing behavior. In npayload, channels handle all routing patterns through routing keys with glob pattern matching. A single channel can serve fan-out, topic-based, and direct delivery patterns simultaneously.

Built-in retry with exponential backoff

In RabbitMQ, implementing retries typically requires a chain of dead-letter exchanges with per-message TTL or a delayed message plugin. npayload includes configurable retry policies with exponential backoff on every subscription. No additional topology required.

No queue declaration needed

RabbitMQ requires explicit queue declaration, binding configuration, and careful management of queue durability and exclusivity settings. npayload subscriptions are created with a single API call, and the underlying delivery infrastructure is managed automatically.

Built-in circuit breaker

When a RabbitMQ consumer fails repeatedly, messages accumulate in the queue until it runs out of memory or disk. npayload's built-in circuit breaker detects failing endpoints, pauses delivery, and routes messages to the dead letter queue. Recovery is automatic once the endpoint is healthy again.

Webhook delivery

RabbitMQ consumers must maintain persistent TCP connections to the broker. npayload can push messages to any HTTP endpoint via webhooks, eliminating the need for long-running consumer processes. This is especially useful for serverless architectures and microservices behind load balancers.

Migration steps

Step 1: Map exchanges and queues to channels and subscriptions

Identify your RabbitMQ exchanges and the queues bound to them. Each exchange typically maps to one npayload channel. Each queue binding maps to one npayload subscription.

import { NPayload } from "@npayload/node";

const npayload = new NPayload({
  appId: "your-app-id",
  apiKey: "your-api-key",
});

// RabbitMQ exchange "orders" with topic routing
// becomes an npayload channel
await npayload.channels.create({
  name: "orders",
  description: "Order lifecycle events",
});

// RabbitMQ queue "order-fulfillment" bound with "order.created"
// becomes an npayload subscription with a routing key filter
await npayload.subscriptions.create({
  channelName: "orders",
  endpoint: "https://fulfillment.example.com/webhooks/orders",
  filter: { routingKey: "order.created" },
  retryPolicy: {
    maxRetries: 5,
    backoffMultiplier: 2,
  },
});

// RabbitMQ queue "order-analytics" bound with "order.*"
// becomes a subscription with a glob pattern
await npayload.subscriptions.create({
  channelName: "orders",
  endpoint: "https://analytics.example.com/webhooks/orders",
  filter: { routingKey: "order.*" },
});

Step 2: Set up dual publishing

During migration, publish to both RabbitMQ and npayload to ensure no messages are lost:

import { NPayload } from "@npayload/node";
import amqp from "amqplib";

const npayload = new NPayload({
  appId: "your-app-id",
  apiKey: "your-api-key",
});

// Dual publish during migration
async function publishOrder(event: string, payload: object) {
  // Existing RabbitMQ publish
  const channel = await rabbitConnection.createChannel();
  channel.publish("orders", event, Buffer.from(JSON.stringify(payload)));

  // New npayload publish
  await npayload.messages.publish({
    channel: "orders",
    routingKey: event,
    payload,
  });
}

Step 3: Migrate consumers one at a time

Switch each RabbitMQ consumer to receive from npayload instead. Start with low-risk consumers (analytics, logging) before moving to critical ones (fulfillment, billing).

Before (RabbitMQ):

import amqp from "amqplib";

const connection = await amqp.connect("amqp://rabbitmq-host");
const channel = await connection.createChannel();

await channel.assertQueue("order-fulfillment", { durable: true });
await channel.bindQueue("order-fulfillment", "orders", "order.created");
await channel.prefetch(10);

channel.consume("order-fulfillment", async (msg) => {
  try {
    const order = JSON.parse(msg.content.toString());
    await processOrder(order);
    channel.ack(msg);
  } catch (err) {
    channel.nack(msg, false, false); // send to DLX
  }
});

After (npayload webhook):

// No consumer process needed. npayload pushes to your endpoint.
// Just set up the subscription (done in Step 1) and handle the webhook:

// In your HTTP server (Express, Fastify, etc.)
app.post("/webhooks/orders", async (req, res) => {
  const { payload, routingKey } = req.body;
  await processOrder(payload);
  res.status(200).send("ok");
});

With npayload, you do not need to manage connections, handle acknowledgments, or configure prefetch counts. Failed deliveries are retried automatically according to your retry policy, and persistently failing messages are routed to the dead letter queue.

Step 4: Switch publishers to npayload SDK

Once all consumers are migrated, update producers to publish only to npayload:

import { NPayload } from "@npayload/node";

const npayload = new NPayload({
  appId: "your-app-id",
  apiKey: "your-api-key",
});

await npayload.messages.publish({
  channel: "orders",
  routingKey: "order.created",
  payload: {
    orderId: "ord_12345",
    customerId: "cust_67890",
    amount: 99.99,
    currency: "USD",
  },
});

Step 5: Decommission RabbitMQ

Once all publishers and consumers have been migrated:

1. Monitor npayload dead letter queues for any delivery failures.
2. Verify message throughput matches your expected volume.
3. Remove the dual-publish code.
4. Shut down RabbitMQ consumers and connections.
5. Decommission RabbitMQ nodes.

What you gain

After migrating from RabbitMQ to npayload, you gain:

• No broker management. No Erlang upgrades, no memory alarms, no disk watermarks, no cluster partitioning to handle.
• Webhook push delivery. No long-lived consumer connections. Messages are delivered to HTTP endpoints automatically.
• Built-in retry and DLQ. Configurable retry policies with exponential backoff and dead letter queues. No manual DLX topology.
• Circuit breaker. Automatic detection of failing endpoints with graceful degradation and recovery.
• Encryption modes. Standard, end-to-end, and hybrid encryption without additional TLS configuration.
• Cross-region messaging. Built-in multi-region support. No Shovel or Federation plugins to install.
• Marketplace. Publish and discover event streams across organizations.

Next steps

• Channels concept for understanding npayload's core messaging primitive
• Subscriptions concept for delivery modes and consumer configuration
• Webhooks guide for webhook delivery setup and best practices