Send events to Amazon SNS
Fan-out to customer-owned SNS topics, one event to many subscribers.
What is Amazon SNS?
Amazon SNS is AWS's pub/sub fan-out service, publish once, deliver to many. As a destination, it lets a customer attach multiple subscribers (SQS queues, Lambda functions, HTTPS endpoints, email, SMS) to a single Pushrail-fed topic. It's the right choice when the customer needs to fan out your events to several internal consumers without operating their own router.
Why deliver events to Amazon SNS
- Fan-out to many subscribers, one event lands in multiple places.
- AWS-native and integrates with SQS, Lambda, EventBridge, and HTTPS endpoints.
- Customer can change subscribers without changing the destination.
- Cheaper than running a Kafka cluster for low-to-mid volumes.
How Pushrail delivers events to Amazon SNS
The SNS adapter calls `Publish` with the canonical event JSON as the message body. Envelope fields are set as `MessageAttributes` so SNS subscription filter policies can route by event type or customer without payload parsing. FIFO topics are supported with the `MessageGroupId` defaulting to `customerExternalId`.
Auth and credentials
Same model as Kinesis, Pushrail authorizes via `sts:AssumeRole` (preferred) or an IAM access key pair scoped to `sns:Publish` on the destination topic ARN. Credentials are encrypted at rest. The customer can lock the trust policy to Pushrail's external ID for tenant isolation.
Batching, retries, and replay
SNS supports `PublishBatch` of up to 10 messages per call; Pushrail uses it when the in-flight buffer accumulates. Transient errors (throttling, 5xx) retry with exponential backoff. Permanent errors (AuthorizationError, NotFound) land in the DLQ. Replay re-emits the same messages with the same `MessageGroupId` so FIFO ordering is preserved.
Example payload
Pushrail accepts the canonical event shape on POST /v1/events. Below is the ingestion request your service makes.
{
"eventType": "order.completed",
"occurredAt": "2026-05-26T14:21:08.493Z",
"source": "billing-service",
"customerExternalId": "acct_8K2zRq",
"idempotencyKey": "order_38a91f-completed",
"correlationId": "req_4f30b2",
"payload": {
"orderId": "ord_38a91f",
"amount": 12900,
"currency": "USD",
"items": [
{ "sku": "PR-PRO-MONTHLY", "qty": 1, "price": 12900 }
]
},
"metadata": {
"tier": "pro",
"region": "us-east-1"
}
}Example configuration
The fields your customer fills in to point Pushrail at their Amazon SNS setup.
{
"type": "SNS",
"name": "Customer SNS topic",
"topicArn": "arn:aws:sns:us-east-1:123456789012:pushrail-events",
"region": "us-east-1",
"fifo": false,
"auth": {
"mode": "ASSUME_ROLE",
"roleArn": "arn:aws:iam::123456789012:role/PushrailSnsPublisher",
"externalId": "acme-ext-7Pq2"
}
}Common use cases
- Fan out a single event stream to many internal subscribers on the customer's side.
- Trigger Lambda functions, populate SQS queues, and ping HTTPS endpoints from one source.
- Pair with subscription filter policies to route different event types to different consumers.
- Lightweight alternative to Kafka for AWS-native customers at low-to-mid volume.
Related destinations
At-least-once delivery into a customer-owned SQS queue, standard or FIFO, native AWS SDK.
Ordered shard delivery into a customer-owned Kinesis Data Stream, configurable partition keys, native AWS SDK.
Deliver events into a customer's EventBridge bus, rule-driven routing inside AWS.
Frequently asked questions
What does delivering to SNS get my customer?
Pub/sub fan-out: Pushrail publishes once to a customer-owned topic and SNS delivers to many subscribers: SQS queues, Lambda functions, HTTPS endpoints, email, or SMS. The customer can change subscribers without changing the Pushrail destination.
Can subscribers route by event type?
Yes. Envelope fields are set as MessageAttributes, so SNS subscription filter policies can route by event type or customer without parsing the payload.
Whose AWS credentials are used?
The customer's. Pushrail authorizes via sts:AssumeRole (preferred) or a scoped IAM access key pair for sns:Publish on the destination topic ARN. Credentials are encrypted at rest, and the trust policy can be locked to Pushrail's external ID for tenant isolation.
What happens if a publish fails?
Transient errors (throttling, 5xx) retry with exponential backoff; permanent errors (AuthorizationError, NotFound) land in the dead-letter queue. Replay re-emits the same messages with the same MessageGroupId, so FIFO ordering is preserved on re-runs.