Event Bus

A Stacktape event bus is a serverless event router built on Amazon EventBridge. Producers publish structured events and pattern-based rules route each event to one or more targets — Lambda functions, SQS queues, and batch jobs. You pay per event with no capacity to manage.

When to use

Use an event bus when you need to route events to multiple independent consumers based on event content. Common scenarios:

  • Fan-out by event type — a single order service publishes OrderPlaced, OrderShipped, and OrderCancelled events. Separate Lambda functions handle each event type independently without the producer knowing about them.
  • Cross-service decoupling — services publish events without knowing who consumes them. New consumers subscribe to existing event patterns without changing the producer.
  • AWS service event routing — react to AWS infrastructure events (EC2 state changes, CodePipeline status, etc.) by routing them from the default event bus to your handlers.
  • Third-party SaaS integration — receive events from SaaS partners (Zendesk, Auth0, Datadog) through EventBridge partner event sources.

When NOT to use

  • Point-to-point task queues — if you have one producer and one consumer processing work items, use an SQS queue. SQS is better for point-to-point work queues because it gives consumers queue semantics such as visibility timeouts and message polling. EventBridge is primarily an event router, not a task queue.
  • Simple pub/sub without content filtering — if every subscriber gets every message and you do not need pattern-based routing, an SNS topic is simpler and lower cost.
  • High-throughput data streaming — EventBridge is designed for event routing, not continuous data ingestion. For ordered, replayable data streams, use a Kinesis stream.
  • Synchronous request-response — EventBridge is fully asynchronous. If your caller needs an immediate response, invoke the downstream service directly or use an HTTP API Gateway.

Basic example

The simplest event bus requires no properties at all. Stacktape creates an event bus resource for decoupling producers and consumers in your stack.

export default defineConfig(() => {
  const orderBus = new EventBus({});

  return {
    resources: { orderBus }
  };
});

Event archiving

EventBridge event archiving stores events published to the bus so you can replay them later. Replayed events are re-delivered to the bus where current rules route them to targets — useful for debugging production issues, populating a new consumer with historical data, or recovering from processing failures.

Enable archiving with archivation.enabled. By default, archiving is disabled. When enabled, archived events are retained indefinitely unless you set retentionDays — for example, 30 days keeps costs predictable while still giving you a full month of replay capability. Setting archivation.enabled back to false deletes the archive.

export default defineConfig(() => {
  const orderBus = new EventBus({
    archivation: {
      enabled: true,
      retentionDays: 30
    }
  });

  return {
    resources: { orderBus }
  };
});
Enable archiving for production event buses. The storage cost is low and the ability to replay events during an incident or when onboarding a new consumer is worth it. When archiving is enabled, the archive ARN is available via $ResourceParam('orderBus', 'archiveArn').

Partner event sources

Amazon EventBridge supports partner event sources — pre-built integrations with third-party SaaS providers (Zendesk, Auth0, Datadog, PagerDuty, and others). Use eventSourceName when you already have a partner event source name for a third-party SaaS integration.

Most teams do not need this. Set eventSourceName only when your integration provides a partner event source name; Stacktape exposes that name on the EventBus resource. For custom application events between your own services, a standard event bus (no eventSourceName) is the right choice.

export default defineConfig(() => {
  const partnerBus = new EventBus({
    eventSourceName: 'aws.partner/example.com/1234567890/my-integration'
  });

  return {
    resources: { partnerBus }
  };
});

Subscribing to events

Lambda functions, batch jobs, and SQS queues subscribe to an event bus by adding an event bus trigger to their events configuration. The trigger specifies an eventPattern that filters which events reach the target — only matching events invoke the consumer. You configure the subscription on the consumer resource, not on the bus itself.

Three resource types can subscribe to event bus events:

The EventBusIntegrationProps shape includes eventPattern, onDeliveryFailure, input, inputPath, and inputTransformer. See the event bus trigger reference for full details on each subscriber type.

Specify the bus using exactly one of three options: eventBusName for a Stacktape-managed bus in the same stack, eventBusArn for an external bus, or useDefaultBus for the default AWS event bus. The eventPattern property filters events by source, detail-type, detail, and other fields — see the event bus trigger reference for the full pattern syntax.

export default defineConfig(() => {
  const orderBus = new EventBus({});

  const orderProcessor = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/order-processor.ts'
    }),
    memory: 512,
    timeout: 30,
    events: [
      {
        type: 'event-bus',
        properties: {
          eventBusName: 'orderBus',
          eventPattern: {
            source: ['order-service'],
            'detail-type': ['OrderPlaced']
          }
        }
      }
    ]
  });

  return {
    resources: { orderBus, orderProcessor }
  };
});

For Lambda targets, EventBridge delivers the event object to the handler. The business payload is conventionally in event.detail:

export const handler = async (event: {
  source: string;
  'detail-type': string;
  detail: { orderId: string; amount: number };
}) => {
  const { orderId, amount } = event.detail;
  console.info(`Processing order ${orderId} for $${amount}`);
  // Process the order...
};
Each event bus rule is evaluated independently. If two Lambda functions subscribe to the same event pattern, both are invoked — there is no competing-consumer behavior like SQS. Design your consumers to handle this fan-out.

Delivery failures

In rare delivery-failure cases, onDeliveryFailure can route failed events to an SQS queue. Use either sqsQueueName for a queue in the same stack or sqsQueueArn for an external queue. For critical workflows, configure onDeliveryFailure with an SQS queue so failed deliveries have a destination you can inspect and retry from.

The trigger also supports payload shaping with input, inputPath, and inputTransformer to customize the event before it reaches the target. See the event bus trigger reference and the API reference below for those options.

Connecting to other resources

Use connectTo on a workload that supports resource access — such as a Lambda function, web service, worker service, or batch job — to grant it permission to publish events to the bus. Stacktape adds the required IAM permissions and injects the bus ARN as an environment variable.

For a bus named orderBus, the injected environment variable is:

Environment variableDescription
STP_ORDER_BUS_ARNThe event bus Amazon Resource Name — use with the AWS SDK to publish events

For more details on connectTo, see Connecting resources.

export default defineConfig(() => {
  const orderBus = new EventBus({});

  const api = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/api.ts'
    }),
    connectTo: [orderBus],
    memory: 512,
    timeout: 30
  });

  return {
    resources: { orderBus, api }
  };
});

Publishing an event from the connected Lambda function:

import { EventBridgeClient, PutEventsCommand } from '@aws-sdk/client-eventbridge';

const client = new EventBridgeClient({});

export const handler = async () => {
  await client.send(new PutEventsCommand({
    Entries: [{
      EventBusName: process.env.STP_ORDER_BUS_ARN,
      Source: 'order-service',
      DetailType: 'OrderPlaced',
      Detail: JSON.stringify({ orderId: '12345', amount: 99.99 })
    }]
  }));

  return { statusCode: 200, body: 'Event published' };
};

Referenceable parameters

The following parameters can be easily referenced using $ResourceParam directive directive.

To learn more about referencing parameters, refer to referencing parameters.

arn
  • Arn of the event bus

  • Usage: $ResourceParam('<<resource-name>>', 'arn')
archiveArn
  • Arn of the event bus archive (available only if the archivation is enabled)

  • Usage: $ResourceParam('<<resource-name>>', 'archiveArn')

API Reference

EventBusProps
Click a property in the tree to see its description, default value, and full type.

Event Bus FAQ

When should I use an event bus vs an SQS queue?

Use an event bus when you need content-based routing to multiple independent consumers — each consumer sees only the events that match its pattern. Use an SQS queue when you have a single consumer processing work items from a queue, and you need built-in retry, dead-letter queues, and visibility timeouts. A common pattern combines both: the event bus routes events to SQS queues, giving each consumer its own buffer.

When should I use an event bus vs an SNS topic?

Both support fan-out to multiple consumers. An event bus excels at content-based routing — you can filter events by source, type, and nested payload fields without extra code. An SNS topic is simpler when every subscriber should receive every message or you only need basic attribute filtering. SNS also supports SMS and email delivery, which EventBridge does not.

How does Amazon EventBridge pricing work?

EventBridge uses pay-per-event pricing with no capacity to provision — you are billed per event published to a custom bus. If you enable event archiving, archive storage and replay incur separate costs, so set retentionDays to keep storage predictable. The model is cost-effective for moderate event volumes but worth monitoring for high-throughput workloads (where a Kinesis stream may be cheaper).

What is the maximum event size for EventBridge?

Amazon EventBridge accepts events up to 256 KB. For larger payloads, store the data in an S3 bucket and include the S3 key in the event's detail field. The consumer retrieves the full payload from S3 when processing the event.

How do I subscribe to events on the default AWS event bus?

AWS provides a default event bus in every region that receives events from AWS services (EC2 state changes, CodePipeline events, etc.). On an event bus trigger, set useDefaultBus: true instead of eventBusName to subscribe to those events — you do not need to create a Stacktape EventBus resource. Combine this with an eventPattern that does deep matching on the detail field (exact values, prefixes, numeric ranges, existence checks) to route only the AWS events you care about.

What happens if an event fails to reach a target?

By default a failed delivery is eventually dropped. Configure onDeliveryFailure on the event bus trigger to route failed events to an SQS queue — use sqsQueueName for a queue in the same stack or sqsQueueArn for an external one. For critical workflows always configure this so undeliverable events have a destination you can inspect and retry from.

Can container services subscribe to event bus events?

Container services (web service, worker service) cannot directly subscribe to event bus events as triggers. Instead, route events from the bus to an SQS queue using an event bus trigger on the queue, then have the container poll the queue using the AWS SDK. Use connectTo to grant the container access to the SQS queue. This gives the container backpressure control and retry semantics.