AWS SNS ExecModule

Overview

AwsSnsModule connects ValkyrAI workflows to Amazon Simple Notification Service through the bundled AWS SDK v2 client. It covers n8n's core create-topic, delete-topic, and publish actions while adding topic and subscription discovery, guarded subscription changes, fixed region routing, verified IntegrationAccount credentials, bounded output, and annotation-backed Workflow Studio discovery.

The connector implements eight operations:

• topic discovery: list_topics, get_topic_attributes
• topic lifecycle: create_topic, delete_topic
• notification delivery: publish
• subscription lifecycle: list_subscriptions_by_topic, subscribe, unsubscribe

Direct SMS, email, mobile-platform endpoints, insecure HTTP subscriptions, topic policy mutation, delivery-policy mutation, confirmation-token handling, tagging, and batch publish are intentionally outside this first governed surface.

Usage

1. Create a dedicated AWS IAM principal scoped to the exact SNS topics and actions the workflow needs.
2. Store its access key ID and secret access key in an AWS IntegrationAccount, verify the account, and keep it in READY status.
3. Add AwsSnsModule to a workflow and bind the account through ExecModuleConfig.authConfig.integrationAccount.
4. Set operation, region, and the operation-specific topic, message, endpoint, pagination, or confirmation fields.
5. Preserve topic ARNs, subscription ARNs, message IDs, and AWS request IDs. Reconcile provider state before replaying an ambiguous write.

Never place AWS credentials in mapped input, message attributes, logs, or examples. Credential-like input fields are rejected before provider access.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the eight documented operations.
region	string	Every execution	None	AWS region syntax such as us-west-2; custom endpoints are not accepted.
topicArn	string	Topic-specific operations	None	Exact SNS topic ARN in the configured partition, region, and 12-digit account.
topicName	string	create_topic	None	1-256 letters, numbers, hyphens, or underscores; FIFO creation appends .fifo when needed.
displayName	string	Optional create_topic	None	At most 100 characters, with no control characters.
fifoTopic	boolean	Optional create_topic	false	Must be true for a .fifo topic.
contentBasedDeduplication	boolean	Optional FIFO create	false	Requires fifoTopic=true.
message	string	publish	None	Non-empty UTF-8 content within the 256 KiB aggregate SNS envelope.
subject	string	Optional publish	None	At most 100 characters, with no control characters.
messageAttributes	object	Optional publish	{}	At most ten non-empty String attributes; AWS/Amazon reserved prefixes and invalid periods are rejected.
messageGroupId	string	FIFO publish	None	Required for FIFO topics; at most 128 bytes. Optional for standard topics.
messageDeduplicationId	string	Optional FIFO publish	None	FIFO only; at most 128 bytes.
protocol	string	subscribe	None	One of https, sqs, or lambda; insecure HTTP, email, SMS, and mobile endpoints are not exposed.
endpoint	string	subscribe	None	Absolute HTTPS URL without embedded credentials/fragments, or a region-matched SQS/Lambda ARN.
subscriptionArn	string	unsubscribe	None	Confirmed SNS subscription ARN in the configured region.
nextToken	string	Optional list resume	None	Opaque AWS continuation, at most 4,096 characters.
limit	integer	List operations	100	1-10,000 results.
returnAll	boolean	List operations	false	Follow provider pages until exhaustion or limit.
confirmSubscribe	boolean	subscribe	false	Must be explicitly true before AWS creates a subscription.
confirmDelete	boolean	delete_topic, unsubscribe	false	Must be explicitly true before either destructive operation.

Outputs

Every execution returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls, including discovery retries and pages.
data	object	Attribute or mutation success	Topic attributes/ARN, publish receipt, subscription receipt, or deletion receipt.
items	array	List success	Bounded topic or subscription records.
count	integer	List success	Number of returned items.
hasMore	boolean	List success	Whether another provider page exists.
nextToken	string	Another page exists	Opaque continuation for a later execution.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation and support.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Subscription items contain bounded subscriptionArn, owner, protocol, endpoint, and topicArn fields. Treat endpoint values and notification bodies as confidential workflow data.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / SNS
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only the actions used by the workflow:

• sns:ListTopics for list_topics
• sns:GetTopicAttributes for get_topic_attributes
• sns:CreateTopic for create_topic
• sns:DeleteTopic for confirmed delete_topic
• sns:Publish for publish
• sns:ListSubscriptionsByTopic for subscription discovery
• sns:Subscribe for confirmed subscribe
• sns:Unsubscribe for confirmed unsubscribe

Restrict resource-scoped actions to the exact topic ARNs. The current connector supports a long-lived access-key pair. Temporary session credentials, role assumption, cross-account role chaining, VPC/custom endpoints, and caller-supplied credentials are deferred.

Configuration

The awsAccount relationship is the only credential configuration. Operation, region, topic, message, endpoint, pagination, and confirmation controls belong in module parameters or mapped input; read retries use the normalized retry policy.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-sns-production"
  },
  "retryPolicy": {
    "maxAttempts": 3
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"publish\",\"region\":\"us-west-2\",\"topicArn\":\"arn:aws:sns:us-west-2:123456789012:agent-events\"}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
list_topics	Lists region topics with opaque token pagination.	Read-only; transient failures retry within the configured bound.
get_topic_attributes	Reads the attributes of one exact topic.	Read-only; transient failures retry.
create_topic	Creates or resolves a named standard/FIFO topic with bounded attributes.	External write; exactly one provider attempt. AWS treats the same name and attributes idempotently but rejects mismatches.
delete_topic	Deletes one exact topic.	Destructive; requires confirmDelete=true; exactly one provider attempt.
publish	Publishes one bounded message and String attributes to a topic.	External fan-out; exactly one provider attempt.
list_subscriptions_by_topic	Lists up to 100 subscriptions per AWS page.	Read-only; transient failures retry.
subscribe	Creates an HTTPS, SQS, or Lambda subscription and asks AWS to return its ARN.	External write; requires confirmSubscribe=true; exactly one provider attempt. HTTPS endpoints still complete AWS confirmation.
unsubscribe	Removes a confirmed subscription ARN.	Destructive; requires confirmDelete=true; exactly one provider attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing or invalid region, ARN, topic, message, endpoint, bound, FIFO option, or confirmation.	No	Correct the named input; no provider request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_SNS_HTTP_400	Invalid ARN, message envelope, endpoint, or FIFO option.	No automatic write retry	Inspect the current topic/subscription state before replay.
AWS_SNS_HTTP_403	IAM denies the action or an account quota is reached.	Provider-dependent	Grant only the required action or resolve the quoted AWS limit.
AWS_SNS_HTTP_404	Topic or subscription is absent or invisible.	No	Verify partition, region, account, and exact ARN.
AWS_SNS_HTTP_429 / 503	Transient provider pressure.	Yes for discovery only	Discovery can retry; reconcile mutations before replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Yes for discovery only	Treat publish and lifecycle outcomes as ambiguous.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve ARNs, message identifiers, and request IDs for reconciliation.

Provider exception text is not copied into output, preventing credential echoes and unbounded error payloads.

Example

Publish a correlated agent event:

{
  "operation": "publish",
  "region": "us-west-2",
  "topicArn": "arn:aws:sns:us-west-2:123456789012:agent-events",
  "subject": "Workflow event",
  "message": "{\"jobId\":\"job-123\",\"action\":\"enrich_customer\"}",
  "messageAttributes": {
    "correlationId": "workflow-2026-09-04-job-123",
    "tenant": "acme"
  }
}

Expected result shape:

{
  "status": "success",
  "operation": "publish",
  "attempts": 1,
  "requestId": "aws-request-reference",
  "data": {
    "messageId": "provider-message-id"
  }
}

Notes

• Pagination: list_topics and list_subscriptions_by_topic preserve AWS tokens as opaque values. returnAll=true follows only the configured region and stops at limit or 10,000 results. AWS returns at most 100 subscriptions per page.
• Rate limits: HTTP 408, 429, 500, 502, 503, and 504 plus network failures can retry only for list/get operations, bounded by RetryPolicy.maxAttempts from 1 through 5. AWS SDK retries are disabled so module accounting and single-attempt writes remain deterministic.
• API limits: message content plus attribute names/types/values is bounded at 262,144 bytes. Subject and display name are bounded at 100 characters. Topic, endpoint, ARN, token, and result counts are also bounded before use.
• Idempotency: create_topic is provider-idempotent only when the existing topic has identical attributes. Standard topic publish has no provider idempotency key. FIFO publish supports a five-minute deduplication window through messageDeduplicationId or content-based deduplication; callers must still reconcile ambiguous responses.
• Destructive behavior: delete_topic removes the topic and its subscriptions; unsubscribe removes delivery to one endpoint. Both require confirmDelete=true and are attempted once.
• Subscription safety: only HTTPS, region-matched SQS, and region-matched Lambda endpoints are allowed. HTTPS subscriptions can remain pending until the endpoint confirms AWS's request; the module does not consume confirmation tokens.
• Delivery semantics: a returned message ID means SNS accepted the message, not that every endpoint delivered it. Subscriber retry, dead-letter, ordering, filtering, and delivery policies remain provider-managed.
• Data handling: messages, attributes, subjects, and subscription endpoints are confidential. The module never logs request or response bodies.
• Provider verification boundary: deterministic tests cover validation, fixed routing, account isolation, request mapping, pagination, retry boundaries, normalization, redaction, registration, FIFO rules, and confirmation guards. Live AWS behavior remains unverified until an authorized SNS credential and reviewed topic are supplied.
• Functional reference: n8n's AWS SNS integration exposes create topic, delete topic, and publish. ValkyrAI adds topic attributes, subscription discovery and lifecycle, strict ARN/endpoint validation, verified IntegrationAccount enforcement, bounded output, explicit confirmations, and conservative single-attempt semantics.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsSnsModule through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• AWS SQS ExecModule
• AWS Lambda ExecModule
• AWS S3 ExecModule
• AWS Fargate Launch ExecModule
• Integration Account Console