Outbound webhooks are available on Team and Enterprise plans.
Prerequisites
- An existing SQS queue in the AWS account and region you want to send to
- The full queue URL, for example
https://sqs.us-east-1.amazonaws.com/000000000000/my-queue - An AWS access key ID and secret access key for a principal that can send messages to that queue
- Permission to manage webhook endpoints in the Novu environment you are configuring
Required AWS permission
Batches are delivered with theSendMessageBatch API, which is authorized by the sqs:SendMessage action on the destination queue. Additional permissions may be required by your own setup, for example KMS key permissions when the queue uses server-side encryption with a customer managed key, or permissions needed to satisfy an organizational policy, service control policy, or queue policy condition.
Novu configures this connector through the embedded webhook portal. The portal collects the queue URL and credentials and does not create the queue or evaluate an IAM policy document for you.
Configuration
These are the fields collected for the Amazon SQS connector.
There is no webhook URL field for this connector. Delivery targets the queue through the AWS SQS API rather than an HTTPS endpoint you host.
Transformation contract
The handler receives a batch and returns the messages to send. The handler receives one delivery batch:input.events, an array whose length is capped by the endpoint batch sizeinput.events[].eventType, the Novu event type, for examplemessage.sentinput.events[].payload, the webhook body
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 is sent as a separate SQS message, and its payload becomes that message’s body. The default template sends one message per event, serialized as JSON:
Novu example
This example keeps the event type at the top level of the body so consumers can route on it without parsing nested fields, and passes the Novu payload through unchanged.Batching and limits
SQS accepts at most 10 messages per batch request, so larger batches are automatically split across multipleSendMessageBatch calls. Do not assume a specific endpoint batch size or wait interval. Design consumers to handle each message independently and to tolerate messages from the same Novu batch arriving in separate requests.
Configure in the Dashboard
1
2
3
Add the endpoint
Open Webhooks in the Novu Dashboard, select Endpoints, click Add Endpoint, and choose Amazon SQS.4
5
6
Select event types
Select the event types you want to queue. Only selected event types reach the endpoint and its transformation, so start with one event type when validating a new queue.Verify delivery
Check the following in AWS after a successful test:- The queue shows available messages, or your consumer receives them.
- Each message body matches the shape your transformation returns.
- Message count grows per returned message rather than per delivered batch.
Troubleshooting
- Access denied on delivery: The credentials cannot perform
sqs:SendMessageon this queue. Check the identity policy, the queue policy, and any condition that restricts the caller. - The queue does not exist or is rejected: Confirm the full queue URL is exact, including account ID and queue name, and that the configured region matches the queue’s region.
- Delivery succeeds but the queue looks empty: Another consumer likely received the messages already, or messages are in flight. Check the in flight metric, or test against a queue with no active consumers.
- Encrypted queues fail: If the queue uses a customer managed KMS key, the credentials also need permission to use that key.
- Message bodies are not valid JSON for consumers: Confirm what your transformation returns in
payload. Returning a string sends that string as the body, while returning an object sends its serialized JSON. - Fewer messages than events: Confirm the transformation returns one entry per event and does not filter or combine events unintentionally.
- Some event types never arrive: Review the endpoint’s selected event types, and test each event type separately from the Testing tab.