Publish webhook events to Amazon SNS

The Amazon SNS connector publishes selected Novu webhook events to an SNS topic. Novu delivers events in batches, and every event in a batch is published to the topic as a separate message. Use this connector to fan a single Novu event out to multiple subscribers, such as an SQS queue, a Lambda function, and an HTTP subscriber at the same time.

Outbound webhooks are available on Team and Enterprise plans.

Prerequisites

An existing SNS topic in the AWS account and region you want to publish to
The topic ARN, for example arn:aws:sns:us-east-1:000000000000:my-topic
An AWS access key ID and secret access key for a principal that can publish to that topic
At least one topic subscription you can inspect during verification
Permission to manage webhook endpoints in the Novu environment you are configuring

Required AWS permission

Batches are delivered with the PublishBatch API, which is authorized by the sns:Publish action on the destination topic. Additional permissions may be required by your own setup, for example KMS key permissions when the topic uses server-side encryption with a customer managed key, or permissions needed to satisfy an organizational policy, service control policy, or topic policy condition. Novu configures this connector through the embedded webhook portal. The portal collects the topic ARN and credentials and does not create the topic, add subscriptions, or evaluate an IAM policy document for you.

Configuration

These are the fields collected for the Amazon SNS connector.

Dashboard field	Required	Description
Topic ARN	Yes	ARN of the destination SNS topic.
Region	Yes	AWS region that hosts the topic.
Access key ID	Yes	AWS access key ID used to authenticate.
Secret access key	Yes	AWS secret access key paired with the access key ID.
Endpoint URL	No	Optional custom endpoint for SNS-compatible services, for example a local development stack. Leave it empty for standard AWS SNS.
Transformation	Yes	JavaScript that shapes the published message body and optional subject.

There is no webhook URL field for this connector. Delivery targets the topic through the AWS SNS API rather than an HTTPS endpoint you host.

Transformation contract

The handler receives a batch and returns the messages to publish. The handler receives one delivery batch:

input.events, an array whose length is capped by the endpoint batch size
input.events[].eventType, the Novu event type, for example message.sent
input.events[].payload, the webhook body

The webhook body wraps the resource in an envelope. payload.object is the resource type as a string, such as "message", and the resource itself is under payload.data.object. For message events, fields such as subscriberId and channel are therefore at event.payload.data.object. Other event families use different resource shapes, so guard extracted fields with defaults. The handler must return:

{
  messages: Array<{
    payload: unknown;
    subject?: string;
  }>;
}

Return field	Behavior
`messages[].payload`	Becomes the SNS message body.
`messages[].subject`	Optional SNS subject for that message. Omitted by default.

The default template publishes one message per event, serialized as JSON, with no subject:

function handler(input) {
  const messages = input.events.map((event) => ({
    payload: event,
  }));

  return {
    messages,
  };
}

With the default template, two events produce two message bodies:

{"payload":{"email":"[email protected]"},"eventType":"user.created"}

{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}

Novu example

This example sets the Novu event type as the subject, which is useful when subscribers filter or display the subject, and keeps the full event in the body.

function handler(input) {
  const messages = input.events.map((event) => ({
    payload: JSON.stringify({
      eventType: event.eventType,
      payload: event.payload,
    }),
    subject: event.eventType,
  }));

  return {
    messages,
  };
}

Subject values are visible to subscribers such as email, so avoid putting subscriber data or other sensitive values in subject. Keep it to the event type or another low cardinality label.

Batching and limits

SNS accepts at most 10 messages per batch request, so larger batches are automatically split across multiple PublishBatch calls. Do not assume a specific endpoint batch size or wait interval. Design subscribers to handle each message independently, because messages from the same Novu batch can be published in separate requests.

Configure in the Dashboard

Prepare the topic

Create the destination topic, copy its ARN, and attach at least one subscription you can inspect, such as an SQS queue you control. Confirm the topic’s region matches the region you will configure.

Create credentials

Create an access key for a principal that can perform sns:Publish on the topic. If the topic is encrypted with a customer managed key, confirm the credentials can use that key.

Add the endpoint

Open Webhooks in the Novu Dashboard, select Endpoints, click Add Endpoint, and choose .

Enter connection details

Enter Topic ARN, Region, Access key ID, and Secret access key. Leave Endpoint URL empty unless you are targeting an SNS-compatible service. Add a description that identifies the topic and AWS account.

Configure the transformation

Start from the provided template and send a test before customizing. Add subject only if your subscribers use it, and keep the body shape stable for existing subscribers.

Select event types

Select the event types you want to publish. Only selected event types reach the endpoint and its transformation, so start with one event type when validating a new topic.

Test the endpoint

Create the endpoint, open Testing, and send an example for a subscribed event type. Confirm the attempt succeeded in Logs, then inspect a subscription and compare the delivered message with the logged transformation output.

Verify delivery

Check the following in AWS after a successful test:

A subscriber received the message, for example the subscribed SQS queue has an available message.
The message body matches the shape your transformation returns, and the subject matches if you set one.
Delivery counts grow per returned message rather than per delivered batch.

A topic without subscriptions accepts publishes and discards them, so always verify through a subscription rather than the topic alone.

Troubleshooting

Access denied on delivery: The credentials cannot perform sns:Publish on this topic. Check the identity policy, the topic policy, and any condition that restricts the caller.
The topic ARN is rejected: Confirm the ARN is exact, including account ID and topic name, and that the configured region matches the region inside the ARN.
Delivery succeeds but nothing is received: The topic likely has no matching subscription, or a subscription filter policy excluded the message. Check the subscription list and its filter policy.
Encrypted topics fail: If the topic uses a customer managed KMS key, the credentials also need permission to use that key.
Subscribers cannot parse the body: Confirm what your transformation returns in payload. Returning a string publishes that string as the body, while returning an object publishes its serialized JSON.
The subject is missing: subject is optional and omitted by the default template. Set it explicitly if subscribers depend on it.
Some event types never arrive: Review the endpoint’s selected event types, and test each event type separately from the Testing tab.

Guides

Publish webhook events to Amazon SNS

Prerequisites

Required AWS permission

Configuration

Transformation contract

Novu example

Batching and limits

Configure in the Dashboard

Prepare the topic

Create credentials

Add the endpoint

Enter connection details

Configure the transformation

Select event types

Test the endpoint

Verify delivery

Troubleshooting

Official references

​Prerequisites

​Required AWS permission

​Configuration

​Transformation contract

​Novu example

​Batching and limits

​Configure in the Dashboard

​Prepare the topic

​Create credentials

​Add the endpoint

​Enter connection details

​Configure the transformation

​Select event types

​Test the endpoint

​Verify delivery

​Troubleshooting

​Related

​Official references

Prerequisites

Required AWS permission

Configuration

Transformation contract

Novu example

Batching and limits

Configure in the Dashboard

Prepare the topic

Create credentials

Add the endpoint

Enter connection details

Configure the transformation

Select event types

Test the endpoint

Verify delivery

Troubleshooting

Related

Official references