Send events to Amazon SQS
At-least-once delivery into a customer-owned SQS queue, standard or FIFO, native AWS SDK.
What is Amazon SQS?
Amazon SQS is AWS's managed work queue, pull-based, with at-least-once delivery and built-in dead-letter queue support. For AWS-native customers, SQS is the canonical queue for backgrounding work triggered by your events. Pushrail writes events as messages; the customer's workers (Lambda, ECS, EC2) pull and process them.
Why deliver events to Amazon SQS
- AWS-native, Lambda has built-in SQS triggers, ECS has SQS consumer patterns.
- Backpressure handled by the customer, workers pull at their own rate.
- FIFO queues preserve per-customer or per-resource ordering when needed.
- Built-in DLQ on the customer's side, independent of Pushrail's DLQ.
How Pushrail delivers events to Amazon SQS
The SQS adapter calls `SendMessageBatch` with up to 10 messages per request. The canonical event JSON is the message body. Envelope fields are set as message attributes. For FIFO queues, the `MessageGroupId` defaults to `customerExternalId` (so per-customer ordering is preserved) and `MessageDeduplicationId` is the event's `idempotencyKey` so SQS dedup catches repeat sends within the 5-minute window.
Auth and credentials
Same as other AWS destinations, `sts:AssumeRole` (preferred) or IAM access key pair scoped to `sqs:SendMessage` and `sqs:SendMessageBatch` on the destination queue ARN. Credentials encrypted at rest. The customer can pin the role's trust policy to Pushrail's external ID for tenant isolation.
Batching, retries, and replay
Batches of up to 10 messages or 256 KB per `SendMessageBatch`. Transient errors (throttling, 5xx) retry with exponential backoff. Permanent errors (AccessDenied, QueueDoesNotExist) land in the DLQ. Replay re-sends with the same `MessageDeduplicationId` on FIFO queues so SQS-side dedup applies; on standard queues, replays may produce duplicates and the customer's worker is expected to be idempotent on `idempotencyKey`.
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 SQS setup.
{
"type": "SQS",
"name": "Customer SQS queue",
"queueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/pushrail-events.fifo",
"region": "us-east-1",
"fifo": true,
"messageGroupIdField": "customerExternalId",
"auth": {
"mode": "ASSUME_ROLE",
"roleArn": "arn:aws:iam::123456789012:role/PushrailSqsWriter",
"externalId": "acme-ext-7Pq2"
}
}Common use cases
- Queue work that a customer's backend processes asynchronously (Lambda, ECS).
- Decouple your event timing from the customer's worker throughput.
- FIFO ordering for per-customer or per-resource workflows.
- Pair with SNS upstream to fan out into multiple queues.
Related destinations
Fan-out to customer-owned SNS topics, one event to many subscribers.
AMQP exchange-and-routing-key delivery into a customer-owned RabbitMQ cluster.
AMQP delivery into a customer-owned Azure Service Bus queue or topic, sessions, dead-letter, scheduled enqueue.
Frequently asked questions
How does Pushrail deliver to SQS?
The adapter calls SendMessageBatch with up to 10 messages per request; the canonical event JSON is the message body and envelope fields are set as message attributes. The customer's workers, Lambda, ECS, or EC2, pull and process at their own rate.
Does SQS delivery preserve ordering?
On FIFO queues, yes. MessageGroupId defaults to customerExternalId, so per-customer ordering is preserved, and MessageDeduplicationId is set from the event's idempotency key so SQS dedup catches repeat sends within its 5-minute window.
Whose AWS credentials are used?
The customer's. They authorize Pushrail via sts:AssumeRole (preferred) or a scoped IAM access key pair for sqs:SendMessage and sqs:SendMessageBatch on the destination queue ARN. Credentials are encrypted at rest, and the role's trust policy can be pinned to Pushrail's external ID for tenant isolation.
Are replays safe on standard queues?
On FIFO queues, replay re-sends with the same MessageDeduplicationId so SQS-side dedup applies. On standard queues, replays may produce duplicates, so the customer's worker is expected to be idempotent on the idempotency key. Permanent errors like AccessDenied land in the dead-letter queue.