AWS SQS

RunReveal sends a JSON message to an Amazon SQS queue when a detection fires, a test runs, or another notification event triggers. Standard and FIFO (.fifo) queues work across all AWS partitions (aws, aws-us-gov, aws-cn).

Setup Instructions

Step 1: Create or Select an SQS Queue

Create or pick the SQS queue that will receive alerts and copy its Queue URL (for example, https://sqs.us-east-1.amazonaws.com/123456789012/runreveal-alerts).

On FIFO (.fifo) queues, RunReveal sets MessageGroupId to runreveal-<workspaceID> and MessageDeduplicationId to <historyID>-<pageIndex> so content-based deduplication does not drop multi-page alerts.

Step 2: Configure AWS Authentication

Authenticate with an IAM role that RunReveal assumes (recommended) or an AWS access key pair.

Create an IAM role in your AWS account with sqs:SendMessage permission on the target queue:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowRunRevealSQSSendMessage",
      "Effect": "Allow",
      "Action": [
        "sqs:SendMessage"
      ],
      "Resource": "arn:aws:sqs:<REGION>:<ACCOUNT_ID>:<QUEUE_NAME>"
    }
  ]
}

If your SQS queue uses server-side encryption (SSE) with a customer-managed KMS key, also grant kms:GenerateDataKey and kms:Decrypt on that KMS key ARN.

Add a trust policy on the role so RunReveal can assume it with your External ID:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::253602268883:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<EXTERNAL_ID>"
        }
      }
    }
  ]
}

Note: BYOC, On-Prem, and BYODB customers must use their deployment's AWS account ID in the Principal ARN instead of 253602268883.

Step 3: Configure in RunReveal

Open Notification Channels, click Connect a notification channel, and select AWS SQS.
Enter a display name and paste your SQS Queue URL (https://sqs.us-east-1.amazonaws.com/123456789012/my-alerts-queue). RunReveal fills in the AWS region from the URL.
Pick Customer provided role (Role ARN and optional External ID) or AWS access key (Access Key ID and Secret Access Key).
Click Test notification to send a test message, then click Create Notification to save.

Payload Schema & Page Splitting

Each SQS message body is a JSON object matching the Webhook notification payload, with two differences for AWS.

Scheduled SQL detections include detection.results (an array of row objects) and omit the columnar columns and values arrays so rows are not duplicated in the payload.

AWS SQS caps messages at 256 KB (262,144 bytes). When a detection result exceeds 256 KB, RunReveal splits detection.results across multiple SQS messages and sets pageIndex (0, 1, 2, ...) and totalPages on each message.

Top-level fields

Field	Type	Description
`title`	string	Rendered notification title (from template).
`body`	string	Rendered notification body (from template).
`channel`	string	Always `"sqs"` for this channel.
`pageIndex`	number	0-based index of this message page (`0` when unsplit).
`totalPages`	number	Total number of pages sent for this notification (`1` when unsplit).
`detection`	object	Present for detection alerts.
`test`	object	Present for test notifications (`{"status": true}`).
`data`	object	Present for other event types.

Example payloads

{
  "title": "RunReveal Detection Alert: Impossible Travel Detected",
  "body": "User [email protected] logged in from two countries within 5 minutes.\n\nSeverity: high\nRows Returned: 1\nResult Link: https://app.runreveal.com/dash/history?alertID=abc123",
  "channel": "sqs",
  "pageIndex": 0,
  "totalPages": 1,
  "detection": {
    "id": "abc123",
    "detectionID": "det_456",
    "workspaceID": "ws_789",
    "name": "impossible-travel",
    "displayName": "Impossible Travel Detected",
    "detectionType": "query",
    "severity": "high",
    "riskScore": 80,
    "categories": ["identity"],
    "mitreAttacks": ["TA0001"],
    "mitreTechniques": ["T1078"],
    "description": "Detects logins from geographically distant locations.",
    "system": false,
    "executedAt": "2025-02-19T12:00:00Z",
    "triggered": true,
    "resultLink": "https://app.runreveal.com/dash/history?alertID=abc123",
    "query": "SELECT actor, srcIP, srcCity FROM events WHERE ...",
    "params": { "from": "2025-02-19T11:00:00Z", "to": "2025-02-19T12:00:00Z" },
    "runTime": 230,
    "resultCount": 1,
    "nextRunTime": "2025-02-19T12:15:00Z",
    "prevRunTime": "2025-02-19T11:45:00Z",
    "results": [
      {
        "__alertID__": "abc123",
        "actor": "[email protected]",
        "srcIP": "203.0.113.42",
        "srcCity": "London"
      }
    ]
  }
}

AWS SNS Notifications - Publish detection alerts to an Amazon SNS topic
Webhooks - Full detection object field reference
Notification Templates - Customize notification title and body
Getting Started with Notifications - Attach notification channels to detections

On this page