Amazon SQS

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, 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 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:

An example policy looks like this:

{
  "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.

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:

{
  "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:

{
  "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:

{
  "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. 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 can be attached to Amazon SQS sources just like any other event source.

Tips and troubleshooting

If you encounter an error or question not listed below and need assistance, don't hesitate to reach out. We're here to help.