View a markdown version of this page

What is the EventBridge Custom Event Bus? - Amazon EventBridge
Key featuresResourcesOne bus, many accountsHow the Custom Event Bus routes and retains eventsHow the Custom Event Bus differs from Custom Event Bus - ClassicUse casesPricingNext steps
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

What is the EventBridge Custom Event Bus?

The EventBridge Custom Event Bus is a serverless event bus that one team runs and many teams and accounts use. You publish events to it with PutEvents or PutRawEvents. It routes each event to the subscribers whose filters match it, and it keeps a copy of every event for a retention period that you set on the bus. You share the bus with other accounts through Amazon Resource Access Manager (Amazon RAM), and each of those accounts attaches its own subscribers. The bus owner writes no routing on their behalf.

In the EventBridge console, the bus type is shown as Custom Event Bus for this bus and Custom Event Bus - Classic for the buses that use rules and targets. For the CLI, SDK, and IAM names, see Names, endpoints, and IAM permissions for the Custom Event Bus.

Key features

  • Cross-account sharing through Amazon RAM, with four managed permissions that let a consumer account publish, subscribe, attach event sources, or all three.

  • Retention of every event for 1 to 365 days, set on the bus.

  • Ordered (FIFO) delivery within an event group, per subscriber.

  • A starting position for each subscriber, so a new subscriber can read retained events and a paused subscriber can resume without loss.

  • Deduplication at publish time, by content or by a key that you supply, within a 5-minute window.

  • PutRawEvents for JSON, Avro, Protobuf, or raw bytes, with schema registry deserialization for filtering.

  • Universal targets that call any state-changing Amazon API action directly, alongside the bespoke targets.

Resources

You work with three resources.

Event bus

The event bus receives the events you publish with PutEvents or PutRawEvents, routes them to subscribers, and retains them. You set the retention period, an optional Amazon KMS key, and optional cross-account sharing on the bus. For the states a bus moves through, see Bus states and what each allows.

Subscriber

A subscriber names the events you want, with filters, and the one target that receives them. You create it with CreateSubscriber. It watches one bus, keeps the events that match its filters, optionally transforms each one, and delivers it to exactly one target. To send an event to several targets, create one subscriber for each target.

Event source

An event source ingests events onto a bus from an Amazon service or from a software as a service (SaaS) partner. You create it with CreateEventSource, naming the origin and the destination bus, and EventBridge moves the events for you.

Bus and subscriber Amazon Resource Names (ARNs) end in an identifier that EventBridge generates, for example arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef. Store the full ARN rather than the name. If you delete a bus and create another with the same name, the new bus has a different identifier.

One bus, many accounts

To let another account use your bus, share it with Amazon RAM and attach one of the managed permissions, for example AWSRAMEventBridgeEventBusV2SubscribeOnly to let that account attach subscribers. The account then creates and owns its own subscribers on your bus: it sees only its subscribers when it lists them, and you see all of them. A consumer account cannot change or delete the bus, and you can withdraw any of its subscribers with RevokeResource. For the permissions, resource policies, and revocation, see Sharing a Custom Event Bus with other accounts.

How the Custom Event Bus routes and retains events

The bus routes each event to matching subscribers as it arrives. The bus also retains the event for the number of days that you configure. Retention makes two capabilities possible.

  • A subscriber can start from a point in the past. That is how you replay retained events, and how a subscriber that you create today reads events that were published yesterday.

  • A subscriber can pause and later resume without losing events.

For more information, see Choosing the retention period and Replaying retained events to a subscriber.

How the Custom Event Bus differs from Custom Event Bus - Classic

Capability Custom Event Bus Custom Event Bus - Classic
Cross-account use Share the bus with Amazon RAM. Each consumer account creates and owns its subscribers on the bus. Grant other accounts through the bus resource policy, or forward events to a bus in the other account.
Retention Built into the bus, for a period that you set. Not retained. To keep events, add an archive.
Ordering FIFO delivery within an event group, per subscriber. Not available.
Replay A subscriber's starting position over retained events. Replay from an archive.
Publish APIs PutEvents for JSON and PutRawEvents for any format, including Avro and Protobuf. PutEvents for JSON.
Deduplication At publish time, by content or by a key that you supply. Not available.
Targets per routing resource One target per subscriber. Up to five targets per rule.

Use cases

  • A platform team runs one orders bus and shares it with the accounts of the fulfillment, billing, and analytics teams. Each team attaches its own subscribers; the platform team never edits routing for them.

  • A payments service publishes with an EventGroupId per account number and a FIFO subscriber delivers each account's events to a queue in order.

  • A new analytics consumer is created with a starting position 30 days back and reads a month of retained events before it catches up to live traffic.

Pricing

You pay for the events you publish, the deliveries to subscribers, and retention. For the rates, see Amazon EventBridge pricing.

Next steps