SQS Listener

Published on Mar 25, 2026
6 minute(s) read

This feature is available in v42.3 and later.

With the SQS Listener Input Block, you can configure connections to Amazon SQS queues. This block replaces Message Queue (MQ) Listener Blocks that have Amazon SQS connections, as those blocks will be removed from the system in v45 of Hyperscience.

If you would like to use an SQS Listener connection in a SaaS instance and your SQS service is not public, you should create a firewall pinhole for the connection. Contact your Hyperscience representative for more information.

Sample use cases

I send submission info from external systems to an Amazon SQS queue. I want to ingest this submission info into Hyperscience for processing.
My customers will post relevant documents and metadata to my Amazon SQS queue. I want to then ingest these documents and metadata for processing into Hyperscience.

Message format

A JSON object must be passed to the queue in order for Hyperscience to read the appropriate input image files. It should have the same format as the request payload for the Submission Creation API endpoint, with one key difference: in the message payload, the files element is an array of file URLs and does not contain individual file_url elements.

An example message payload is shown below.

JSON

{
  "flow_uuid": "a89d6440-a2c2-423b-8c95",
  "machine_only": "true",
  "files": [
    "s3://s3-bucket/input/demo-file.pdf",
    "https://example.com/files/demo-file.pdf",
    "ocs://2021",
    "gs://bucket/example.pdf",
    "abs://container-name/blob.pdf",
    "abs://container-name/blob.pdf?sas=secret-token"
  ]
}

For more information about the Submission Creation payload, see the Submission Creation section of our API documentation.

Migrating from the Message Queue Listener Block

Message Queue Listener Blocks with Amazon SQS connections will continue to work in v42.3, v43, and v44. However, they will be removed in v45 of Hyperscience. If you are using the Message Queue Listener Block to connect to Amazon SQS queues, you will need to migrate to the SQS Listener Block before upgrading your application to v45.

Other connection types (i.e., ActiveMQ, IBM MQ, or RabbitMQ) can continue to be used in Message Queue Listener Blocks, as no migration is required to maintain those connection types in future versions.

To migrate to the SQS Listener Block, follow the steps below.

1. Identify affected flows.

Look for warnings/errors mentioning MQ_LISTENER with MQ_TYPE=AMAZON_SQS.

2. In each affected flow, add an SQS Listener Block.

See Setting up a connection in Hyperscience to learn how to add the SQS Listener Block.

3. Transfer your settings from the Message Queue Listener Block to the SQS Listener Block.

Transfer your Amazon SQS configuration to the new dedicated SQS block, including the queue URL, AWS credentials/authentication settings, and any other SQS-specific settings.

The table below provides a mapping of settings from the Message Queue Listener Block to the SQS Listener Block.

Message Queue Listener setting	SQS Listener setting
Queue URL	SQS Queue URL
AWS Region	Region Name
Use AWS EC2 Instance IAM Role Credentials	Use Default Credential Chain
Access Key ID	AWS Access Key ID
Secret Access Key	AWS Secret Access Key

The Consume Timeout and Consume Num Messages settings are new in the SQS Listener.

To learn more about these settings, see Block settings.

4. Disable the Amazon SQS Message Queue Listener connection and enable the SQS Listener connection.

Disabling the Message Queue Listener connection before enabling the SQS Listener connection helps in the processing of duplicate messages.

To enable or disable a connection, click on Inputs in Flow Studio, then toggle the switch for the connection to the on (blue) or off (gray) position.

For more information on managing connections, see Managing Connections.

5. Test the updated flow.

Deploy the updated flow in your lower environment.
Verify that message consumption / notification behavior works as expected.
Confirm that no deprecation warnings appear for the flow.

6. Deploy the updated flow in production.

After testing is complete in your lower environment, deploy the updated flow in production before upgrading to v45.

If you need additional assistance with the migration or with migration planning, contact your Hyperscience representative.

Block settings

In addition to the settings outlined below, you can also configure the settings described in Universal Integration Block Settings.

Name	Required?	Description
SQS Queue URL	Yes	The queue URL for sending messages.
Region Name	Yes	The AWS region of the source data.
Consume Timeout	Yes	Maximum time, in seconds, that the consumer will wait for new messages. Defaults to 10.
Consume Num Messages	Yes	Sets the maximum number of messages the consumer fetches in a single consumption cycle. Defaults to 1.
Use Default Credential Chain	Yes	If selected, credentials are obtained from the EC2 instance directly. Selected by default.
AWS Access Key ID	Yes, if Use Default Credential Chain is not selected	The access key ID allows access to the message queue.
AWS Secret Access Key	Yes, if Use Default Credential Chain is not selected	The secret access key allows access to the message queue.

Setting up SQS Listener connections

SQS Listener connections require configuration in both Hyperscience and AWS.

Setting up a connection in Hyperscience

To set up the SQS Listener Block in Hyperscience, follow these steps.

Log in to your Hyperscience instance.
Go to Flows, and click on the flow you want to add the SQS Listener to.
Click Edit Flows.
In Flow Studio, click on Inputs.
Click Add and select SQS Listener from the list.
Click the Add Connection button.
Enter the block settings described above.

Setting up a connection in AWS

Go to your Amazon Simple Queue Service.
Choose or create the relevant input queue. The SQS Listener supports standard and FIFO queues.
Grant the following permissions via the AWS Interface:
- sqs:ReceiveMessage
- sqs:GetQueueUrl
- sqs:DeleteMessage
- sqs:ChangeMessageVisibility

Visibility timeout

To avoid duplicate processing, configure the queue's visibility timeout to at least 60 seconds.

Message size

Note that Amazon imposes certain limitations on the size of messages sent to queues as documented in AWS’s Amazon SQS quotas. At the time of writing this article, the maximum message size allowed is 256KB.

Dead-letter queues

A dead-letter queue (DLQ) is a specialized message queue designed to temporarily hold messages that encounter processing errors within a software system. Hyperscience recommends setting the maximum number of retry attempts for a message to be between 3 and 5.

Setting up DLQs

To set up a DLQ, see the instructions in AWS’s Configuring a dead-letter queue redrive.