What it actually is
Amazon EventBridge is a family of three routing products that share a name, a console, an IAM namespace, and a filter language. The event bus routes events from many publishers to many consumers who never know about each other. Pipes connects exactly one source (a queue, a stream, a broker) to exactly one target, with optional filtering and enrichment in between. Scheduler invokes a target at a time or on a recurring schedule. People say "EventBridge" and mean any of the three, which is why so many designs pick the wrong one.
The other thing the docs will not tell you up front: as of September 24, 2026 there are two kinds of custom event bus. The original, built on rules and targets, is now labeled "Custom event bus - classic". The new one, which AWS simply calls the Custom event bus and some posts call the enhanced bus, uses subscribers instead of rules, keeps events for 1 to 365 days, supports ordering and content-based deduplication, can be shared across accounts through AWS RAM, and is billed per GB instead of per event. It has its own CLI command (aws eventsv2), its own SDK client (eventbridgev2 in boto3), and its own ARN type (event-busv2). Existing classic buses keep working, unchanged. The default bus that receives AWS service events is still a classic bus.
This article is a reference for all of it, with the build on the new bus, because that is where new designs should start unless one of the reasons below sends you back to classic.
The model
The event. On both buses, PutEvents takes an envelope: Source, DetailType, Detail (your JSON), optional Resources and Time. Since January 29, 2026 the maximum event payload is 1 MB, up from 256 KB. The new bus adds PutRawEvents, which accepts arbitrary payloads (JSON-based formats such as CloudEvents keep their shape, and Avro or Protocol Buffers can be deserialized to JSON for filtering).
Classic bus: rules and targets. A rule is an event pattern plus up to 5 targets. The bus owner writes rules. Delivery is asynchronous, retried for up to 24 hours and 185 attempts by default, with an optional DLQ per target. History exists only if you create an archive, and replay is a separate API that re-publishes archived events to the bus.
New bus: subscribers. A subscriber is one filter configuration, one target, one retry policy, one dead-letter queue, an optional batch configuration, an optional JSONata transformer, and a starting position. Fan-out to five targets means five subscribers. Consumers can own their subscribers in their own accounts while a platform team owns the shared bus. The key properties:
Retention is built in. Every event is stored for the bus's
RetentionPeriodInDays(default 1 day, up to 365). There is no archive resource.Replay is a starting position. A subscriber created with
POINT_IN_TIMEreads from retained history, either from the oldest retained event (HORIZON) or from aTIMESTAMP, optionally stopping at anEndPoint. Without anEndPointit catches up and keeps delivering live events. Each delivered event carriesaws:DeliveryTypeasLIVEorREPLAY.Ordering is opt-in per subscriber. Publishers set an
EventGroupId. A subscriber of typeFIFOreceives events with the same group ID in sequence;UNORDEREDsubscribers on the same bus are unaffected.Deduplication is opt-in per publish. With
DeduplicationConfigurationset toCONTENT_BASED, identical events within a fixed 5-minute window are collapsed andPutEventsreturnsSuccessCode: DEDUPLICATEDfor the duplicate.Synchronous invocation. Lambda and Step Functions targets can be invoked with
REQUEST_RESPONSE, so an event is acknowledged only after the function succeeds. That removes the SQS buffer people used to put between a bus and a Lambda just to get acknowledgement.
Pipes. A pipe polls a source (SQS, Kinesis, DynamoDB Streams, Amazon MQ, Amazon MSK, or any Apache Kafka) and delivers to one target, with a filter, an optional enrichment step (Lambda, Step Functions Express, API destination, or API Gateway), and an input transform. If the source enforces order, the pipe preserves it. A pipe is point-to-point plumbing, not a router.
Scheduler. A schedule is an at(), rate(), or cron() expression with a time zone, an optional flexible time window, and a target. It can delete itself after a one-time run (ActionAfterCompletion: DELETE). It scales to 10 million schedules per Region by default.
Who operates what. AWS runs the buses, storage, retries, and scaling. You own the contract: event shapes, filter correctness, idempotent consumers, IAM roles, and what happens to events that land in a DLQ. EventBridge will happily deliver nothing forever if your filter is shaped wrong, and it will not tell you.
When to use it, when not to
You need | Use | Not |
|---|---|---|
Many independent consumers, filtered routing, cross-account | New Custom event bus | SNS if you need content filtering over the whole event, replay, or RAM sharing |
React to AWS service events (EC2 state, S3 object created) | Default bus (classic) rules, or event sources routed onward | Polling APIs |
One queue or stream into one target, with filter and enrichment | Pipes | A Lambda that only forwards messages |
Run something at 09:00 Paris time, or once in 3 days | Scheduler | Classic scheduled rules (Scheduler has time zones, one-time schedules, and 10M schedules) |
A work queue with backpressure and consumer-controlled pace | SQS | Any bus |
Fan-out with the cheapest per-message cost and simple attribute filters | SNS | A bus, if you do not need replay |
Ordered, high-throughput stream with many readers at their own offsets | Kinesis or MSK | A bus (500,000 events per second per bus is a hard limit on the new bus) |
Multi-step workflow with state and compensation | Step Functions | A chain of events with no owner |
Stay on classic for now if you need global endpoints, a feature only rules provide, a Region the new bus has not reached (it launched in 14 Regions: N. Virginia, Ohio, Oregon, Ireland, Frankfurt, Stockholm, Spain, Tokyo, Singapore, Sydney, Malaysia, Thailand, Mumbai, Hong Kong), or mostly large events (see the next section). Earlier entries in this series cover the neighbors: SQS (SL#162) and SNS (SL#163).
What it costs
The two buses bill on different axes, and that is the decision most people will get wrong.
Classic bus: custom and partner events ingested cost $1.00 per million, and each 64 KB chunk of a payload counts as one event. AWS management events are free to ingest. Delivery to a target in the same account is free; delivery to another bus costs $1.00 per million. Archives cost $0.10 per GB processed plus $0.023 per GB-month stored, and replayed events are billed like published events.
New bus: ingress is $0.18 per GB for the first 5,000 GB per month, then $0.12 per GB. Egress is $0.05 per GB per subscriber delivery, retries included. Storage beyond the default retention is $0.08 per GB. Deduplication and JSONata transformation are "event evaluations" at $0.15 per million, charged only when configured. Every event is rounded up to 1 KB. AWS's own example: 1,000 events per second at 2 KB, two subscribers, one JSONata transform, dedup on, 7-day retention, about $2,317 per month, of which dedup and JSONata are $778.
The surprise is event size. Classic charges per event (per 64 KB chunk); the new bus charges per byte. With one subscriber and first-tier ingress, the new bus costs $0.23 per GB moved. I ran the numbers for one million events per month:
Event size | New bus, 1 subscriber | Classic, same account |
|---|---|---|
1 KB | $0.23 | $1.00 |
2 KB | $0.46 | $1.00 |
4 KB | $0.92 | $1.00 |
8 KB | $1.84 | $1.00 |
64 KB | $14.72 | $1.00 |
1 MB | $235.52 | $16.00 |
Break-even is about 4.3 KB per event with one subscriber, 3.0 KB with three, 2.3 KB with five (every subscriber adds egress). Small, chatty domain events are much cheaper on the new bus, and cross-account fan-out stops costing a dollar per million per hop. Fat events are much cheaper on classic. The usual fix is the same in both worlds: put the large payload in S3 and publish a pointer.
Pipes: $0.40 per million requests after filtering, 64 KB chunks. Filtered-out messages are free, so filter in the pipe, not in the target. Scheduler: $1.00 per million invocations, with 14 million free per month. API destinations: $0.20 per million. Schema Registry is free; schema discovery has a free tier of 5 million events per month.
Free tier reality: Scheduler and schema discovery have one. The buses and Pipes do not. The pricing page does not list a free tier for the new bus.
The limits that bite
New bus. 5 buses owned per account per Region (adjustable; shared buses do not count). 10,000 subscribers per bus. 500,000 events per second per bus, not adjustable. 1,500 events-plus-KB per second per EventGroupId, not adjustable, so a single hot ordering key is your real throughput ceiling. Up to 100 entries per PutEvents. At most three filters per subscriber, one per scope, 4,096 bytes total, no wildcards, 1,000 $or combinations. Filters can change only 24 times per rolling 24 hours. Subscriber creates and deletes are serialized per bus: a second concurrent call fails with ConcurrentModificationException. Default retry is 5 attempts within 300 seconds, far shorter than classic's 24 hours. Dedup window is 300 seconds, not configurable.
Classic bus. 300 rules per bus (100 in Cape Town and Milan), 30 rules with wildcards, 5 targets per rule (hard), event pattern 2,048 characters. PutEvents is throttled per Region in requests per second: 10,000 in us-east-1, us-west-2 and eu-west-1, as low as 400 in smaller Regions. Target invocations over the limit are delayed, not dropped.
Shared. API destinations default to 300 invocations per second each, and that limit is shared by every rule and subscriber pointing at the same destination.
Pipes. 1,000 pipes per account, and 3,000 concurrent executions in the largest Regions (1,000 elsewhere).
Scheduler. 10,000,000 schedules per Region, CreateSchedule at 5,000 TPS in 11 primary Regions (raised in March 2026), invocations at 1,000 TPS there. Target Input is capped at 256 KB.
Build it
We will build an order-events flow on the new bus in us-east-1: a subscriber that only sees orders over 500, an SQS target with a DLQ, content-based deduplication on publish, and then a replay of everything the bus retained into a second queue, with no archive. Finally a one-shot Scheduler job that deletes itself.
Prerequisites. Python 3.10+, boto3 recent enough to include the eventbridgev2 client (the code was checked against botocore 1.44.2), and credentials for an account in a Region where the new bus is available.
IAM for you (the caller). events:CreateEventBus, events:DescribeEventBus, events:DeleteEventBus, events:CreateSubscriber, events:DeleteSubscriber, events:PutEvents; sqs:CreateQueue, sqs:GetQueueAttributes, sqs:ReceiveMessage, sqs:DeleteQueue; iam:CreateRole, iam:PutRolePolicy, iam:PassRole, iam:DeleteRolePolicy, iam:DeleteRole; scheduler:CreateSchedule. Note the prefix: IAM actions for the new bus use events:, not eventsv2:. IAM accepts a policy naming eventsv2:PutEvents, but that action does not exist, so it grants nothing.
Cost of following along. A dozen events of under 1 KB, a few SQS calls, one schedule invocation, and one day of default retention. Well under one cent.
Step 1: queues and a delivery role. The subscriber assumes a role trusted by events.amazonaws.com (the same principal as classic) that can send to the target and to the DLQ.
import json, time, datetime as dt
import boto3
REGION = "us-east-1"
sqs = boto3.client("sqs", region_name=REGION)
iam = boto3.client("iam")
ebv2 = boto3.client("eventbridgev2", region_name=REGION)
sched = boto3.client("scheduler", region_name=REGION)
def queue(name):
url = sqs.create_queue(QueueName=name)["QueueUrl"]
arn = sqs.get_queue_attributes(QueueUrl=url, AttributeNames=["QueueArn"])["Attributes"]["QueueArn"]
return url, arn
big_url, big_arn = queue("sl-orders-large")
dlq_url, dlq_arn = queue("sl-orders-large-dlq")
rep_url, rep_arn = queue("sl-orders-replay")
trust = {"Version": "2012-10-17", "Statement": [{"Effect": "Allow",
"Principal": {"Service": ["events.amazonaws.com", "scheduler.amazonaws.com"]},
"Action": "sts:AssumeRole"}]}
role_arn = iam.create_role(RoleName="sl-eventbus-delivery",
AssumeRolePolicyDocument=json.dumps(trust))["Role"]["Arn"]
iam.put_role_policy(RoleName="sl-eventbus-delivery", PolicyName="send",
PolicyDocument=json.dumps({"Version": "2012-10-17", "Statement": [{
"Effect": "Allow", "Action": "sqs:SendMessage",
"Resource": [big_arn, dlq_arn, rep_arn]}]}))
time.sleep(10) # IAM is eventually consistent; a fresh role can fail to assume for a few seconds
One role trusted by both EventBridge and Scheduler keeps the demo short. In production, give each service its own role.
Step 2: the bus. CreateEventBus returns while the bus is CREATING. Publishing or subscribing before it is ACTIVE fails.
bus = ebv2.create_event_bus(Name="sl-orders",
StorageConfiguration={"RetentionPeriodInDays": 1})
bus_arn = bus["EventBusArn"]
while ebv2.describe_event_bus(EventBusArn=bus_arn)["State"] != "ACTIVE":
time.sleep(3)
print("bus", bus_arn)
Step 3: a filtered subscriber with a DLQ. For events published with PutEvents, the DATA scope matches the envelope, so your fields live under detail. The retry policy is set explicitly because the default gives up after 5 minutes.
sub = ebv2.create_subscriber(
Name="large-orders",
EventBusArn=bus_arn,
FilterConfiguration={"Filters": [
{"Scope": "DATA", "Pattern": json.dumps({"detail": {"total": [{"numeric": [">", 500]}]}})},
{"Scope": "SYSTEM_METADATA", "Pattern": json.dumps({"aws:Source": ["sl.checkout"]})},
]},
InvokeConfiguration={"TargetArn": big_arn, "RoleArn": role_arn},
RetryPolicy={"MaxRetryAttempts": 20, "MaxEventAgeInSeconds": 3600},
OnFailureConfiguration={"Arn": dlq_arn},
StartingPosition="LATEST",
)
large_sub_arn = sub["SubscriberArn"]
time.sleep(30) # let the new subscriber attach before publishing; LATEST skips earlier events
The SYSTEM_METADATA filter on aws:Source matters: source inside the event data is whatever a publisher wrote, while aws:Source is set by EventBridge.
Step 4: publish, with deduplication. Order 1001 is small, 1002 is large, and 1002 is sent twice with identical content.
def order(oid, total):
return {"Source": "sl.checkout", "DetailType": "OrderPlaced",
"Detail": json.dumps({"orderId": oid, "total": total})}
resp = ebv2.put_events(
EventBusArn=bus_arn,
Entries=[order("1001", 120), order("1002", 900), order("1002", 900)],
DeduplicationConfiguration={"DeduplicationType": "CONTENT_BASED"},
)
print("failed:", resp["FailedEntryCount"])
for e in resp["Entries"]:
print(e.get("SuccessCode"), e.get("EventId"), e.get("ErrorCode"))
Always check FailedEntryCount. PutEvents can succeed as a call while individual entries fail, on both buses. The expected codes here are PUBLISHED, PUBLISHED, DEDUPLICATED.
Step 5: verify the filter. Only order 1002 should arrive, once.
def drain(url, seconds=60):
got, end = [], time.time() + seconds
while time.time() < end:
r = sqs.receive_message(QueueUrl=url, MaxNumberOfMessages=10, WaitTimeSeconds=10)
for m in r.get("Messages", []):
got.append(m["Body"])
sqs.delete_message(QueueUrl=url, ReceiptHandle=m["ReceiptHandle"])
if got:
break
return got
bodies = drain(big_url)
print(len(bodies), "message(s)")
for b in bodies:
print(b[:400])
Success is one message containing "orderId": "1002". If you see 1001, the filter is wrong. If you see nothing, check the DLQ before anything else: an access problem ends up there as a JSON record with an errorCode such as ACCESS_DENIED.
Step 6: replay without an archive. Create a second subscriber that starts at the oldest retained event and stops now. Because it has an EndPoint, it is exempt from the rule that open-ended point-in-time subscribers must start at least 5 minutes in the past. No filter means every event. WITH_METADATA asks for the system metadata in the delivered body so you can see the delivery type.
now = dt.datetime.now(dt.timezone.utc)
rep = ebv2.create_subscriber(
Name="replay-all",
EventBusArn=bus_arn,
InvokeConfiguration={"TargetArn": rep_arn, "RoleArn": role_arn},
StartingPosition="POINT_IN_TIME",
PointInTimeConfiguration={"PointType": "HORIZON", "EndPoint": now},
Transformer={"Type": "WITH_METADATA"},
)
replay_sub_arn = rep["SubscriberArn"]
for b in drain(rep_url, seconds=300):
print(b[:400])
Expect orders 1001 and 1002, each once, marked REPLAY. A replay has a startup delay before it runs at live speed, so give it a few minutes before deciding it failed. This same mechanism is the DLQ redrive: the DLQ holds records, not events, so you fix the cause, then create a point-in-time subscriber filtered on the failed aws:EventId values.
Step 7: a one-shot schedule. Scheduler delivers straight to SQS, then deletes itself.
at = (dt.datetime.now(dt.timezone.utc) + dt.timedelta(minutes=2)).strftime("%Y-%m-%dT%H:%M:%S")
sched.create_schedule(
Name="sl-reminder-once",
ScheduleExpression=f"at({at})",
ScheduleExpressionTimezone="UTC",
FlexibleTimeWindow={"Mode": "OFF"},
Target={"Arn": rep_arn, "RoleArn": role_arn,
"Input": json.dumps({"kind": "abandoned-cart-check", "orderId": "1001"})},
ActionAfterCompletion="DELETE",
)
print(drain(rep_url, seconds=240))
That is the honest division of labor: the bus routes facts to whoever cares, Scheduler fires on time, and neither replaces the queue that absorbs the work.
When it breaks
ConcurrentModificationException on CreateSubscriber or DeleteSubscriber. Subscriber changes are serialized per bus. Retry with backoff; do not create subscribers in parallel in a loop.
AccessDeniedException on publish with a policy that looks right. The policy says eventsv2:PutEvents. Use events:PutEvents and events:PutRawEvents, scoped to the event-busv2 ARN. If one entry in a batch fails authorization, the whole request is denied.
The subscriber receives nothing and nothing errors. A filter written for the wrong shape matches nothing silently. PutEvents patterns need the detail wrapper; PutRawEvents patterns do not; METADATA never matches PutEvents events. Test every filter with one event that should match and one that should not.
Events published right after creating a subscriber are missing. LATEST means after the subscriber exists. Publish after it is attached, or use a point-in-time start.
DLQ fills with ACCESS_DENIED. The delivery role cannot be assumed, lacks sqs:SendMessage, or the queue's KMS key denies it. If the role cannot write to the DLQ either, records are lost and only the OnFailureDestinationFailed metric tells you.
Lambda handler breaks after migrating from classic. On the new bus a function receives a JSON array, even with a batch size of 1. Classic sends one event per invocation.
A downstream outage longer than 5 minutes drops events to the DLQ. That is the new default retry policy. Set MaxEventAgeInSeconds to 86400 if you relied on classic's 24-hour retries, and remember that updating RetryPolicy replaces the whole policy.
Classic: rule fires, target never runs. Usually a missing resource policy on the target (SQS queue policy, Lambda permission) or a target with no DLQ, where failures vanish after 24 hours of retries. Watch the FailedInvocations metric.
ThrottlingException. On classic, it is the per-Region PutEvents request quota: batch up to 10 entries per call and request an increase. On the new bus, more likely a hot EventGroupId at 1,500 events-plus-KB per second. Spread group IDs.
Cleanup
Delete subscribers one at a time (they are serialized), then the bus, then the queues and the role. The schedule already deleted itself after running.
for arn in (large_sub_arn, replay_sub_arn):
for attempt in range(10):
try:
ebv2.delete_subscriber(SubscriberArn=arn)
break
except ebv2.exceptions.ConcurrentModificationException:
time.sleep(5)
time.sleep(15)
ebv2.delete_event_bus(EventBusArn=bus_arn)
for url in (big_url, dlq_url, rep_url):
sqs.delete_queue(QueueUrl=url)
iam.delete_role_policy(RoleName="sl-eventbus-delivery", PolicyName="send")
iam.delete_role(RoleName="sl-eventbus-delivery")
print(ebv2.list_event_buses())
Confirm list_event_buses no longer shows sl-orders and sched.list_schedules() shows no sl-reminder-once. Retention on a deleted bus stops accruing, and with one-day retention there was no storage charge to begin with.
A note on honesty: every API name and parameter above was checked against AWS documentation and validated against the botocore 1.44.2 service model, but the script was not executed against a live AWS account for this article. If a step behaves differently, the docs in Sources win.

