Migrate from AWS SNS/SQS

If you are coming from AWS SNS and SQS, you will find that npayload unifies the functionality of multiple AWS services into a single platform. SNS topics, SQS queues, EventBridge schema registries, and Lambda-based webhook delivery all collapse into npayload channels, subscriptions, and the event catalogue. This guide maps your AWS messaging knowledge to npayload and walks through a practical migration.

Concept mapping

Key differences

One service instead of three

AWS messaging typically requires combining SNS (fan-out), SQS (queuing), and EventBridge (schema registry, routing). Each service has its own API, IAM permissions, monitoring, and failure modes. npayload provides all of these capabilities in a single service with a unified SDK.

Built-in webhook delivery

Delivering SNS messages to HTTP endpoints in AWS typically requires an SNS HTTP subscription with confirmation, or a Lambda function triggered by SNS/SQS that makes the HTTP call. npayload delivers webhooks natively with configurable retries, exponential backoff, and circuit breaker protection.

Richer delivery features

npayload includes a circuit breaker that automatically detects failing endpoints and pauses delivery, routing messages to the dead letter queue until the endpoint recovers. AWS SQS relies on visibility timeout and redrive policies, which can lead to messages cycling repeatedly before reaching the DLQ.

Simpler cross-region

SNS cross-region subscriptions require cross-account IAM policies, separate topic ARNs per region, and manual subscription management. npayload provides cross-region messaging as a built-in capability with no additional configuration per region.

Event catalogue included

AWS EventBridge includes a schema registry, but it is a separate service from SNS/SQS. npayload's event catalogue is integrated directly into the messaging layer, providing schema validation at publish time without additional infrastructure.

No IAM complexity

AWS messaging requires IAM policies for every interaction: publishing to SNS, subscribing SQS to SNS, consuming from SQS, and accessing EventBridge. npayload uses OAuth 2.0 with DPoP for machine-to-machine authentication, providing a simpler and more portable security model.

Migration steps

Step 1: Map SNS topics and SQS queues to npayload channels and subscriptions

Identify your SNS topics and the SQS queues subscribed to them. Each SNS topic maps to an npayload channel. Each SQS subscription maps to an npayload subscription.

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

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

// SNS topic "order-events" becomes an npayload channel
await npayload.channels.create({
  name: "order-events",
  description: "Order lifecycle events",
});

// SQS queue subscribed to SNS with filter policy { "event_type": ["order.created"] }
// becomes an npayload webhook subscription with a routing key filter
await npayload.subscriptions.create({
  channelName: "order-events",
  endpoint: "https://fulfillment.example.com/webhooks/orders",
  filter: { routingKey: "order.created" },
  retryPolicy: {
    maxRetries: 5,
    backoffMultiplier: 2,
  },
});

// SQS FIFO queue becomes a message group subscription
await npayload.subscriptions.create({
  channelName: "order-events",
  endpoint: "https://billing.example.com/webhooks/orders",
  filter: { routingKey: "order.*" },
  ordered: true, // Enables FIFO delivery per group key
});

Step 2: Set up connectors for dual-write

npayload includes built-in SQS and EventBridge connectors that can bridge messages during migration. This lets you run both systems in parallel without custom code.

// Bridge from existing SQS queue to npayload
await npayload.connectors.create({
  type: "sqs",
  config: {
    queueUrl: "https://sqs.us-east-1.amazonaws.com/123456789/order-events",
    region: "us-east-1",
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    },
  },
  channelName: "order-events",
});

Step 3: Migrate consumers

Replace Lambda functions or SQS polling consumers with npayload subscriptions.

Before (AWS Lambda triggered by SQS):

// AWS Lambda handler
import { SQSEvent } from "aws-lambda";

export const handler = async (event: SQSEvent) => {
  for (const record of event.Records) {
    const message = JSON.parse(record.body);
    const snsMessage = JSON.parse(message.Message);
    await processOrder(snsMessage);
  }
};

After (npayload webhook):

// Standard HTTP endpoint. No Lambda, no SQS parsing, no SNS envelope unwrapping.
app.post("/webhooks/orders", async (req, res) => {
  const { payload, routingKey } = req.body;
  await processOrder(payload);
  res.status(200).send("ok");
});

Notice the difference: with AWS, your Lambda must parse the SQS event wrapper, then the SNS message envelope, then the actual payload. With npayload, your webhook receives the payload directly.

Step 4: Switch publishers to the npayload SDK

Before (AWS SNS):

import { SNSClient, PublishCommand } from "@aws-sdk/client-sns";

const sns = new SNSClient({ region: "us-east-1" });

await sns.send(
  new PublishCommand({
    TopicArn: "arn:aws:sns:us-east-1:123456789:order-events",
    Message: JSON.stringify({ orderId, amount, customerId }),
    MessageAttributes: {
      event_type: {
        DataType: "String",
        StringValue: "order.created",
      },
    },
  })
);

After (npayload):

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

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

await npayload.messages.publish({
  channel: "order-events",
  routingKey: "order.created",
  payload: { orderId, amount, customerId },
});

The npayload SDK eliminates ARN management, region configuration, message attribute serialization, and IAM credential handling.

Step 5: Decommission AWS resources

Once all publishers and consumers have been migrated:

1. Verify npayload delivery metrics and check dead letter queues for failures.
2. Remove the SQS/EventBridge connectors.
3. Delete SNS subscriptions (SQS, Lambda, HTTP).
4. Delete SQS queues and their associated DLQ queues.
5. Delete SNS topics.
6. Remove IAM policies and roles associated with the messaging infrastructure.
7. Remove EventBridge schema registry entries if applicable.

What you gain

After migrating from AWS SNS/SQS to npayload, you gain:

• Single unified service. One SDK, one dashboard, one set of concepts. No more wiring SNS to SQS to Lambda to DLQ.
• Native webhook delivery. Push messages to HTTP endpoints without Lambda functions or SQS polling.
• Circuit breaker. Automatic detection of failing endpoints with graceful degradation. No more messages cycling through visibility timeouts.
• Event catalogue. Schema versioning and validation integrated into the messaging layer. No separate EventBridge schema registry.
• Simpler authentication. OAuth 2.0 with DPoP replaces IAM policies, resource-based policies, and cross-account trust relationships.
• Cross-region built in. Multi-region messaging without cross-account SNS subscriptions or SQS queue mirroring.
• ASP protocol. Agent Session Protocol for structured communication between autonomous systems.
• Marketplace. Publish and discover event streams across organizations.

Next steps

• Channels concept for understanding npayload's core messaging primitive
• Connectors guide for bridging npayload with AWS services and other systems
• Event catalogue concept for schema versioning and validation