> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon SQS

> Hightouch and Amazon SQS integration

## Overview

Hightouch supports streaming events from Amazon SQS queues. Hightouch continuously polls your queue, converts each message into a Hightouch event, and deletes the message from the queue once it's processed. Your data can then be synced to your warehouse or streamed to Hightouch's catalog of real-time destinations.

Both standard and FIFO queues are supported.

## Setup

To get started, [**create an event source**](https://app.hightouch.com/events/sources/new?from=docs), select **Amazon SQS**, and follow the steps below.

### Configure your credentials

Amazon SQS sources require AWS credentials. You can select existing AWS credentials or create new ones using either of these methods:

* A cross-account role (recommended)
* An access key

For step-by-step instructions on both methods, see [Connect to your AWS account](https://docs.hightouch.com/destinations/amazon-sqs.md#connect-to-your-aws-account) in the Amazon SQS destination docs. Use the permissions in the next section instead of the ones listed there.

### Grant permissions

Hightouch believes in the principle of least privilege and asks for no more permissions than necessary. For the Amazon SQS event source, attach a policy with these permissions to your role or IAM user:

| Queue | Required permissions |
| - | - |
| Source queue | `sqs:GetQueueUrl`, `sqs:ReceiveMessage`, `sqs:DeleteMessage` |
| Dead-letter queue (optional) | `sqs:GetQueueUrl`, `sqs:SendMessage` |

An example policy looks like this:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["sqs:GetQueueUrl", "sqs:ReceiveMessage", "sqs:DeleteMessage"],
      "Resource": "arn:aws:sqs:us-east-1:123456789012:my-queue"
    },
    {
      "Effect": "Allow",
      "Action": ["sqs:GetQueueUrl", "sqs:SendMessage"],
      "Resource": "arn:aws:sqs:us-east-1:123456789012:my-queue-dlq"
    }
  ]
}
```

If your queues use server-side encryption with a customer managed AWS KMS key, also grant `kms:Decrypt` on that key for the source queue, and `kms:GenerateDataKey` and `kms:Decrypt` for the dead-letter queue.

### Configure your source

Configure the following fields in Hightouch:

* **Region** — The AWS region your queue is in.
* **Queue name** — The name of the queue to consume events from, for example `my-queue`. FIFO queue names end in `.fifo`.
* **DLQ queue name** (optional) — A queue in the same region where Hightouch sends messages it can't process. See [Dead-letter queue](#dead-letter-queue).

### Message format

Events requires the body of each SQS message to be a JSON object or array. Messages that aren't valid JSON, or that exceed the maximum event size, can't be processed.

### Dead-letter queue

If Hightouch encounters a fatal error while processing a message, such as a body that isn't valid JSON, it sends the message to the dead-letter queue (DLQ) you configured and deletes it from the source queue. If you don't configure a DLQ, Hightouch drops those messages.

Each DLQ message body is a JSON object that contains the original message and the error:

```json theme={null}
{
  "message": {
    "id": "3f1c9e2a-8b4d-4c1e-9f7a-2d6b5e8c1a90",
    "body": "not valid json",
    "truncated": false,
    "attributes": {
      "a1": "abc"
    }
  },
  "error": "Unexpected token o in JSON at position 1"
}
```

Hightouch truncates the original body if it's too large to fit in an SQS message and sets `truncated` to `true`. Each DLQ message also has a `hightouchEventSourceId` message attribute that identifies the event source that sent it.

## Event structure

All events are ingested into Hightouch as `track` events. The SQS message ID, the parsed message body, and string-valued message attributes are exposed as `id`, `data`, and `attributes` in the event's `properties`. The queue name and region are exposed in the `context.sqs` object.

By default, the `messageId` is the SQS message ID, and the `timestamp` is when the message was sent to the queue.

For example, the following SQS message:

```json theme={null}
{
  "MessageId": "3f1c9e2a-8b4d-4c1e-9f7a-2d6b5e8c1a90",
  "Body": "{\"user_id\": \"user_123\", \"amount\": 123.45}",
  "MessageAttributes": {
    "a1": { "DataType": "String", "StringValue": "abc" }
  }
}
```

Will be ingested into Hightouch as:

```json theme={null}
{
  "type": "track",
  "event": "My SQS Source Event",
  "messageId": "3f1c9e2a-8b4d-4c1e-9f7a-2d6b5e8c1a90",
  "properties": {
    "id": "3f1c9e2a-8b4d-4c1e-9f7a-2d6b5e8c1a90",
    "data": {
      "user_id": "user_123",
      "amount": 123.45
    },
    "attributes": {
      "a1": "abc"
    }
  },
  "context": {
    "sqs": {
      "queueName": "my-queue",
      "region": "us-east-1"
    }
  },
  "timestamp": "2026-09-25T14:52:37.648Z"
}
```

If you don't map the `event` field, the event name defaults to your event source's name followed by `Event`.

### Field mappings

You can configure how Hightouch transforms messages from your SQS queue to Hightouch [`track` events](https://docs.hightouch.com/events/event-spec#track-events). Mappings can be configured for the following fields:

* `event`
* `userId`
* `anonymousId`
* `messageId`
* `timestamp`

You can also transform your events using Functions to standardize the schema or enrich its contents.

### Schema enforcement

[Event Contracts](https://docs.hightouch.com/events/contracts/management.md) can be attached to Amazon SQS sources just like any other event source.

## Tips and troubleshooting

If you run into an issue this page doesn't cover, [contact support](#pylon-chat).