Store webhook events in Amazon S3

The Amazon S3 connector writes selected Novu webhook events to an S3 bucket. Novu delivers events in batches, and each delivered batch creates one new object in the bucket. Use this connector to build a durable event archive for replay, auditing, or downstream processing with tools that read from S3.

Outbound webhooks are available on Team and Enterprise plans.

Prerequisites

An existing S3 bucket in the AWS account and region you want to write to
An AWS access key ID and secret access key for a principal that can write objects to that bucket
Permission to manage webhook endpoints in the Novu environment you are configuring

Required AWS permission

The connector writes each batch as an object, so the credentials need the s3:PutObject action on the destination bucket. Additional permissions may be required by your own setup, for example KMS key permissions when the bucket enforces server-side encryption with a customer managed key, or permissions needed to satisfy an organizational policy, service control policy, or bucket policy condition. Novu configures this connector through the embedded webhook portal. The portal collects bucket and credential values and does not create the bucket, apply a bucket policy, or validate an IAM policy document for you.

Configuration

These are the fields collected for the Amazon S3 connector.

Dashboard field	Required	Description
Bucket	Yes	Name of the destination S3 bucket.
Region	Yes	AWS region that hosts the bucket.
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.
Transformation	Yes	JavaScript that sets the object key, the object format, and the object contents.

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

Transformation contract

Object storage connectors run the handler once per delivery batch. 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:

{
  config: {
    format: "jsonl" | "json" | "raw";
    key: string;
  };
  data: unknown[] | string;
}

Return field	Behavior
`config.format`	`"jsonl"`, `"json"`, or `"raw"`. Defaults to `"jsonl"`.
`config.key`	Object name for this batch. A timestamp is appended after the transformation runs, so each batch produces a unique object.
`data`	The batch contents. Use an array for `"jsonl"` and `"json"`. Use a string for `"raw"`.

The default template returns the batch unchanged:

function handler(input) {
  return {
    config: {
      format: "jsonl",
      key: "object-generated-by-svix",
    },
    data: input.events,
  };
}

With "jsonl", each line is one event:

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

Novu example

This example groups objects by date and keeps each payload intact:

function handler(input) {
  const partition = new Date().toISOString().slice(0, 10);

  const data = input.events.map((event) => ({
    eventType: event.eventType,
    payload: event.payload,
  }));

  return {
    config: {
      format: "jsonl",
      key: `novu-events/dt=${partition}/events`,
    },
    data,
  };
}

The connector appends a timestamp to config.key, so use the key for the prefix structure rather than adding a uniqueness suffix.

Batching behavior

One delivered batch produces one object. Treat its contents as a variable-length batch and read it line by line when using "jsonl".

Configure in the Dashboard

Prepare the bucket

Create the destination bucket in the region you plan to configure, and decide on the key prefix you want, for example a date partition. If the bucket enforces encryption with a customer managed key, confirm the credentials can use that key.

Create credentials

Create an access key for a principal that can perform s3:PutObject on the bucket. Store the secret access key securely, because it is entered once into the connector configuration.

Add the endpoint

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

Enter connection details

Enter Bucket, Region, Access key ID, and Secret access key. Add a description that identifies the destination, for example the bucket name and the AWS account it belongs to.

Configure the transformation

Start from the provided template. Change config.key to the prefix you want and keep config.format aligned with the type of data you return.

Select event types

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

Test the endpoint

Create the endpoint, open Testing, and send an example for a subscribed event type. Confirm the attempt succeeded in Logs, then list the bucket under your key prefix and confirm a new timestamp-suffixed object exists. Download the object and confirm its contents match the format you configured.

Verify delivery

Check the following in AWS after a successful test:

The object exists under the prefix you set in config.key, with a timestamp appended.
The object contents parse in the format you selected, one JSON document per line for "jsonl".
The object count grows by one per delivered batch rather than one per event.

Troubleshooting

Access denied on delivery: The credentials cannot perform s3:PutObject on this bucket. Check the bucket policy, the identity policy, and any condition that restricts the caller, prefix, or encryption headers.
The bucket or region is rejected: Confirm the bucket name is exact and the region matches the bucket’s actual region. A bucket in another region will not accept the request.
Delivery succeeds but no object appears: You are likely looking at the wrong prefix. Compare the transformed output in Logs with the config.key value, then list the bucket at that prefix.
Object contents are not what you expect: Confirm config.format matches the type of data. For "raw", data must be a string containing the exact contents.
Encrypted buckets fail: If the bucket requires a customer managed KMS key, the credentials also need permission to use that key.
Some event types never appear: Review the endpoint’s selected event types, and test each event type separately from the Testing tab.

Guides

Store webhook events in Amazon S3

Prerequisites

Required AWS permission

Configuration

Transformation contract

Novu example

Batching behavior

Configure in the Dashboard

Prepare the bucket

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 behavior

​Configure in the Dashboard

​Prepare the bucket

​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 behavior

Configure in the Dashboard

Prepare the bucket

Create credentials

Add the endpoint

Enter connection details

Configure the transformation

Select event types

Test the endpoint

Verify delivery

Troubleshooting

Related

Official references