Amazon Eventbridge Event Bus

Building with the new EventBridge custom event buses

Overview

The new EventBridge custom event bus routes events and retains them. You publish with one of two APIs, and subscribers filter, optionally transform, and deliver each matching event to one target.

Read chapters 5 and 6 before writing any filter, transformer, or target parameter. The two publish APIs deliver different payload shapes, and an expression written for one silently matches nothing against the other.

Publish metrics are on by default, so you can always tell whether events reached a bus. Subscriber logs are off by default, so turn them on before you debug a delivery rather than after (chapter 18).

Works best with the AWS MCP server, which is recommended for running the CLI calls in this skill: it executes them in a sandboxed environment with audit logging. All guidance also works with standard AWS CLI access.

Conventions

The key words MUST, MUST NOT, SHOULD, and MAY in this skill are to be interpreted as described in RFC 2119. They appear only in decision procedures, where following the wrong course either breaks the configuration or loses events silently. MUST marks an absolute requirement, SHOULD a strong recommendation you may have a specific reason to set aside, and MAY a genuine option.

Everything else is ordinary description. A sentence stating how the service behaves carries no keyword, because it is a fact rather than an instruction to you.

When not to use this skill

This skill is only about the new custom event buses, the service you reach with the eventsv2 CLI and the eventbridgev2 SDK clients. It does not cover:

• Classic EventBridge, meaning the events API with rules, targets, archives, and event patterns on AWS::Events::Rule. The two services share the events: IAM namespace and some vocabulary, which is exactly why they are easy to confuse. If you are writing a rule, you are not on a new bus. Chapter 3 maps the concepts across if you are migrating.
• EventBridge Pipes, Scheduler, and Schemas (the classic schema registry and its discovery feature). Different APIs.
• Configuring the Firehose service itself, such as buffering hints or record transformation. A Firehose delivery stream is a valid subscriber target; chapter 9 covers that side of it.

Trigger examples

1. "Write a filter so this subscriber only gets orders over $500."
2. "My producer says PUBLISHED but nothing shows up in the queue. What do I check?"
3. "Should I use PutEvents or PutRawEvents for Protobuf payloads?"
4. "Set up a subscriber that reprocesses everything from the last two days."
5. "Write a JSONata expression that pulls the customer id out of the event into a DynamoDB putItem."

Guardrail — where this skill's own files live (MCP vs local install)

This skill can be loaded two ways, and they resolve the skill's own bundled files from different places. Determine how the skill was loaded before reading a reference:

• Loaded through the AWS MCP retrieve_skill tool: The skill is not installed on the local filesystem. You MUST fetch each reference via retrieve_skill with the file parameter (e.g. file="references/setup-walkthroughs.md"). Do NOT file_read these paths locally — they do not exist on disk.
• Installed locally (e.g. .kiro/skills/amazon-eventbridge-event-bus/ or ~/.claude/skills/amazon-eventbridge-event-bus/): Read files from the local skill directory using relative paths.

This distinction applies only to the skill's own packaged files. User data and session artifacts are always read from and written to the user's working directory. Never fetch or write customer data through retrieve_skill.

Reference files

The chapters below carry the decisions and the failure modes; the detail lives in these files. Load a file when the task matches its row, and do not load them all by default.

1. The three resources

Event bus. The thing you publish to. It routes events and retains them.

Subscriber. A statement of which events you want and where to send them, in one resource. It watches its bus, keeps the events matching its filter, optionally transforms each one, and delivers it to exactly one target. To send one event to several targets, create several subscribers on the same bus.

Event source. A managed feed into a bus, either AWS service events or a partner/SaaS source.

Names and identifiers:

• A bus ARN and a subscriber ARN both end in a service-generated id after the name: arn:aws:events:us-east-1:111122223333:event-busv2/my-bus/exampleid0123456789abcdef. Store the full ARN, not the name, because the name alone does not identify the resource and re-creating a deleted bus with the same name yields a different id.
• Event source names are unique per account, not per bus.
• Three names identify this service and they do not match. The CLI command and the endpoint host are eventsv2, as in aws eventsv2 create-event-bus and eventsv2.{region}.amazonaws.com. The SDK clients are eventbridgev2. IAM actions and ARNs are events, shared with classic EventBridge, as in events:PutEvents and arn:aws:events:...:event-busv2/.... See chapter 14.

2. A router with a durable log behind it

The bus routes each event to matching subscribers, and it also retains events for a configured period, set per bus with StorageConfiguration.RetentionPeriodInDays (1 to 365 days). Retention is what makes four other features possible: starting positions, pausing and resuming, replay, and a subscriber created today reading events published yesterday. The retention window is clamped at the bus's creation time, so on a young bus even a recent past timestamp can fall outside it.

3. Coming from classic EventBridge

A classic rule plus its target becomes one subscriber on the new bus. Four new-bus concepts have no classic analogue: retention on the bus itself, a subscriber starting position, pause and resume with a backlog, and two publish APIs with different payload models. That last changes how you write filters, so a classic event pattern ported unchanged works only for PutEvents. The concept mapping, the habits that carry over incorrectly, and a step-by-step migration sequence are in migrating-from-classic.md.

4. AWS service and partner event sources

An event source is a managed feed onto your bus. You create one naming a destination bus and one origin, and the service stands up the forwarding on the classic EventBridge side for you. There is no role and no delivery code: the managed path uses the service's own identity.

Configuration is discriminated and exactly one variant MUST be set:

Both take an optional Pattern, which narrows what forwards and is evaluated on the classic side against the classic envelope. Your pattern MUST NOT carry a source key or a top-level account or region, because the service sets those itself to pin the forward to your account and origin.

A forwarded event arrives as the whole classic envelope. Data holds it, ContentType is application/eventbridge+json, your content is at $events.Data.detail, and the source and detail-type are in SystemMetadata as aws:Source and aws:DetailType. So a classic rule's source filter does not transfer: the equivalent is a SYSTEM_METADATA filter, {"aws:Source":["aws.s3"]}.

Only that SystemMetadata pair proves an AWS service or partner produced the event. No publish call can write either key. A raw payload can imitate the envelope exactly, so a DATA filter on the payload's source matches a forgery as readily as the real thing. You SHOULD filter on aws:Source whenever provenance matters, and MUST match its value rather than its presence, because a direct PutEvents sets the key too, from its own never-aws.-prefixed Source.

EventBusArn is immutable. Recovery splits by failure: from CREATE_FAILED or UPDATE_FAILED, UpdateEventSource converges the classic side back to your record, while from DELETE_FAILED the only recovery is another delete.

A bus owner's control is at create time. CreateEventSource is authorized against the destination bus with an events:source condition key, and RevokeResource is how an owner stops a feed that already exists (chapter 22). Prerequisites, encryption, dead-lettering, and what appears in your classic account are in event-sources.md.

5. Choosing a publish API

The choice fixes the payload shape, and the payload shape determines every filter, transformer, and target parameter you go on to write.

Use PutEvents for JSON events where you want the classic-shaped envelope. Use PutRawEvents for binary or non-JSON payloads, your own metadata keys, or a payload delivered exactly as sent.

Both return one result entry per request entry in the same order, so you correlate by index. Each carries either a SuccessCode or an ErrorCode and ErrorMessage. SuccessCode is PUBLISHED or DEDUPLICATED, and DEDUPLICATED is a success, not an error. Code that treats every success as a new event makes deduplication look like delivery.

Publishing Avro or Protobuf requires a schema registry named on each publish request, not on the bus; a registry configured in the wrong place leaves your events undecoded. application/octet-stream needs no registry, because the service does not decode those bytes at all (schema-registries.md).

6. Addressing: where every field lives

Filters, transformers, and target parameters share one addressing model, and it is not the same for the two publish APIs. Every event is delivered under three top-level names: Data (the payload), Metadata (your own keys, PutRawEvents only), and SystemMetadata (service-assigned and ordering fields). A raw-published payload sits directly in Data; a PutEvents payload sits inside the classic envelope, one level down under detail. So the same field is $events.Data.m for one API and $events.Data.detail.m for the other, and the wrong form does not error: it resolves to nothing, the filter matches nothing, and the transformer emits nothing. If you publish through both APIs onto one bus, write expressions that work for both, or give each traffic type its own subscribers; no addressing form spans both. Both envelopes in full, with every SystemMetadata field, are in filters-and-expressions.md.

7. Filtering

A subscriber's FilterConfiguration holds a list of Filters, and an event must match every filter in the list to be delivered: the filters are ANDed, not ORed. Each filter has a Pattern and a Scope (DATA, METADATA, or SYSTEM_METADATA), one filter per scope. A DATA pattern is written against the chapter 6 shape, so one pattern cannot serve both publish APIs; each is correct for exactly one API and silently matches nothing for the other. FilterConfiguration is optional on create, and a subscriber without one receives every event on the bus. A filter that matches nothing is indistinguishable from a broken subscriber, so confirm a should-match and a should-not-match case by observing the target.

8. Transformation

A subscriber's Transformer has three types: RAW (the default) delivers the payload alone, WITH_METADATA delivers the three-part envelope, and JSONATA delivers the result of an expression. A JSONata expression is wrapped in {% %} delimiters and sees the event as $events, addressed exactly as in chapter 6. Most scalar target parameters also accept an expression in the same form. Some members refuse one and MUST be literals: an API Gateway header name, a message attribute's BinaryValue, and InvocationType. An expression is only syntax-checked at create, so its result is a delivery-time fact. A JSONATA transformer whose expression throws, or evaluates to nothing, is a customer-fault delivery failure, so you SHOULD test it.

9. Targets and their parameter blocks

InvokeConfiguration carries the TargetArn, the RoleArn, and at most one parameter block, matching the target. A universal target MUST carry its block; every typed block may be omitted. A classic bus and a Firehose delivery stream are both valid targets that take no block at all.

The service resolves the target type from the ARN and checks the invariants it owns before storing anything: that the block matches the target, that the ARN's region, partition and account are its own, and that every expression parses. It does not mirror the target API's own parameter grammars, value ranges, identifier limits, or which members that API requires — those stay with the target, so a request the target will reject is accepted at create and fails at delivery.

1. You MUST supply the parameter block a universal target requires. A typed block may be omitted: KinesisParameters: {} is stored, and Kinesis reports the missing PartitionKey when it is called.
2. You MUST NOT put a constant in a per-message field, because a constant deduplication id makes the target discard everything after the first message. Neither form is checked against the target's range, requiredness or FIFO applicability, so a bad or missing value is a delivery failure.
3. You SHOULD check the target service's own rules. Existence, reachability, authorization, size after enveloping, and its API's required fields are enforced by the target, at delivery.
4. You SHOULD confirm at the target, because a PUBLISHED response is not delivery, and neither is an HTTP 200 from a batch API, which can carry individually failed entries.
5. You MUST attach a dead-letter queue and turn on logs before you test, and MUST grant the delivery role sqs:SendMessage on that queue, because a failure otherwise leaves no signal anywhere.

Each rule's failure mode, the exact rejection messages, and the per-target blocks are in target-configuration.md. Before writing the call itself, load target-contract.md for the required-field lists, one working example per target type, and the delivery error taxonomy.

10. Universal targets

A universal target invokes any supported AWS API directly, with no intermediate function. The target ARN has a fixed shape:

arn:{partition}:events:::aws-sdk:{service}:{apiAction}

Four things to get right, each of which fails at create time with a message that names the problem: apiAction is camelCase with a lowercase first letter (putItem); service is the SDK service id, which is not always the obvious word (Step Functions is sfn); UniversalTargetParameters.Input is required and holds the API request as JSON or a JSONata expression producing it; and BatchConfiguration is required. The service's validation text abbreviates universal target as "USI target"; the two mean the same thing.

11. Ordering and deduplication

Ordering is a subscriber property. Type is UNORDERED (no guarantee) or FIFO (ordered within an event group), and events are grouped by SystemMetadata.EventGroupId at publish time. A FIFO target enforces its own length and character limits on the group id, and an undeliverable event holds up the later events in its own group while other groups on the same subscriber keep flowing, so keep group ids bounded and do not derive them from unbounded input.

Deduplication happens at publish time, two ways. DeduplicationConfiguration.DeduplicationType: CONTENT_BASED on the request hashes the event content, and CONTENT_BASED is the only DeduplicationType value. To deduplicate on your own key instead, omit DeduplicationConfiguration and set SystemMetadata.DeduplicationId on each entry. A suppressed duplicate returns SuccessCode: DEDUPLICATED either way.

Keep the two ideas separate. Bus-level deduplication decides whether an event is accepted. A FIFO target's own deduplication id, set in the target parameter block, decides whether that target accepts the delivery. Different fields at different layers, and the second is a per-message value (chapter 9, rule 2).