Published on · Updated on
Rewrote the guide to correct EventBridge delivery, batching, retry, and monitoring guidance; added current service distinctions, limits, replay considerations, and AWS documentation.
Amazon EventBridge can route events, connect a supported source directly to a target, or invoke an API on a schedule. Those jobs use different EventBridge features, and their delivery limits and recovery behavior differ. Use the practices below to choose the right feature, avoid lost or repeated work, and measure delivery rather than assuming a successful publish means the target completed its work.
Quick guide: use an event bus for event routing, Pipes for a point-to-point source-to-target connection, and EventBridge Scheduler for one-time or recurring time-based invocations. For each path, test filters, handle per-entry publish results, make side effects safe to repeat, and monitor the target.
For Custom Event Bus - Classic, give each business event a stable source and detail-type, and document the fields and types in detail. A small, explicit contract makes producer and consumer changes easier to coordinate. Add a version field or use a new event type when a change would break existing consumers. The example below shows the Classic event envelope; the newer Custom Event Bus can also accept raw payloads with a different structure.
{
"source": "com.example.orders",
"detail-type": "OrderPlaced",
"detail": {
"schemaVersion": 1,
"orderId": "order-123",
"status": "PAID",
"total": 135
}
}EventBridge Schema Registry can infer schemas from observed events, manage schemas, and generate code bindings. Discovery helps you understand event shapes; it does not reject nonconforming events at publish time. If publishers must enforce a contract, validate their payloads in application code. AWS recommends JSON Schema for this client-side validation. See the Schema Registry overview, schema discovery, and schema creation guidance.
For Custom Event Bus - Classic, an event pattern selects which events a rule receives. Start with the event source and type, then add only the fields that express the consumer's real interest. Fields omitted from a pattern do not constrain a match, and string matching is case-sensitive unless you select an operator that changes that behavior. The example below is a Classic event-envelope pattern.
{
"source": ["com.example.orders"],
"detail-type": ["OrderPlaced"],
"detail": {
"status": ["PAID"],
"total": [{ "numeric": [">", 100] }]
}
}Test patterns against representative matching and nonmatching events in the EventBridge Sandbox or with TestEventPattern before deploying them. Include boundary values, missing fields, and casing differences in those examples. Avoid duplicate JSON keys in a pattern: only the last repeated key is used. AWS documents the supported event pattern structure, comparison operators, and pattern best practices. For a broader approach to testing AWS service integrations, see our guide to end-to-end testing AWS applications.
For Custom Event Bus - Classic, the default event-pattern size quota is 2,048 characters and can be increased. Check the separate quota page for the newer Custom Event Bus and for your account's Region before designing around a limit.
The newer Custom Event Bus applies patterns through subscriber filters with DATA, METADATA, and SYSTEM_METADATA scopes. A DATA filter matches the payload's shape, not the Classic event envelope shown above. See the subscriber filter documentation before translating a Classic rule.
For the rules-based EventBridge bus (now called Custom Event Bus - Classic when you create a custom bus), design target processing to tolerate duplicate deliveries. AWS describes at-least-once delivery and notes that, in rare cases, a rule or target can run more than once for the same event. Classic event buses do not guarantee event ordering. Do not use EventBridge's event ID as a substitute for a business idempotency key.
Use a stable business key to recognize repeated work. For a database mutation, a conditional write or transaction can record that key with the business result. For an external operation such as charging a payment, reuse an idempotency key supported by the receiving API and account for an uncertain response. A local “processed” record alone cannot make an external call atomic. AWS's Builders' Library explains how idempotent APIs make retries safe.
If event order matters, choose a service and configuration that provides the ordering you need. The newer Custom Event Bus supports optional publish-time deduplication and FIFO delivery within an event group for a FIFO subscriber; those features have defined scope and do not remove the need to make downstream effects safe. See AWS guidance on duplicate target invocations, its event delivery and ordering comparison, and the new bus's ordering and deduplication behavior.
Batching can reduce publish API calls, but a batch is not an all-or-nothing transaction and it does not create per-rule batch settings. On a Classic bus, PutEvents accepts at most 10 entries per request, and the total entry size must be under 1 MB. Each entry can succeed or fail independently. Check FailedEntryCount and the result for every entry, then retry only entries that failed.
The newer Custom Event Bus has separate publish APIs and limits: its PutEvents and PutRawEvents requests accept up to 100 entries. Read the per-entry result there as well. A successful HTTP response alone does not prove every event was accepted, and an accepted event does not prove a subscriber delivered it. Keep Classic and newer-bus limits separate when sizing a producer. See Classic PutEvents batching and partial failures, the Classic API limits, and the new Custom Event Bus publish APIs.
EventBridge target retries handle delivery failures, such as a throttled or temporarily unavailable target. On a Classic bus, the default retry policy allows up to 185 retry attempts over a maximum event age of 24 hours, with exponential backoff and jitter; you can change the maximum age and retry count per target. A newer Custom Event Bus subscriber defaults to up to five retry attempts (in addition to the initial delivery attempt) within a maximum event age of 300 seconds. See the newer bus MaxRetryAttempts definition. Set the policy for the bus type and the target's recovery behavior rather than copying one default everywhere.
Configure a standard Amazon SQS dead-letter queue (DLQ) when an undelivered target event needs investigation or redrive. The DLQ captures EventBridge delivery failures after its retry behavior; it does not capture failed producer PutEvents entries, events that match no rule, or work that a target accepted and then failed internally. Some permanent target errors, such as missing permissions or a deleted resource, can go directly to the DLQ without retrying. Fix the cause before redriving, and monitor the consumer's own failures separately. See AWS guidance for Classic target retries, Classic target DLQs, and new Custom Event Bus subscriber retries.
Measure the full path from event acceptance to target delivery. For Classic event buses, use CloudWatch metrics such as InvocationAttempts, SuccessfulInvocationAttempts, FailedInvocations, InvocationsSentToDlq, and IngestionToInvocationSuccessLatency. Alert on sustained failures, DLQ growth, throttling, and latency that exceeds your application's needs.
The newer Custom Event Bus reports separate metrics in the AWS/EventsV2 namespace, including EventsDelivered, EventsDropped, RetryInvocationAttempts, and ApproximateBacklogAge. Check the namespace and dimensions for the bus type in use. EventBridge metrics show delivery to the target; they do not prove that the target completed the business operation. Pair them with the target's own success, error, and queue-backlog signals. See AWS's Classic delivery monitoring recommendations and new Custom Event Bus observability guide.
Choose based on how work starts and how many consumers need the event:
For every target, confirm that the target can absorb expected traffic and that its permissions allow EventBridge to invoke it. A target may impose a lower request or payload limit than EventBridge. Pipes supports payloads up to 6 MB, but the effective limit is whichever is lower: the Pipes limit or the target's limit. For example, a pipe targeting an EventBridge bus is limited to 1 MB, and one targeting Step Functions is limited to 256 KB. Review the event bus concepts, Pipes, Scheduler, and Pipes payload limits documentation.
Quotas are not one EventBridge-wide events-per-second number. Classic PutEvents request rates vary by Region (400 requests per second in many Regions and up to 10,000 in some), and its rule invocation quota is separate. The newer Custom Event Bus has a default ingestion quota of 500,000 events per second per bus. Pipes and Scheduler have separate quotas, and a target can throttle delivery below the bus quota. Check the current Classic EventBridge quotas, Custom Event Bus quotas, and Service Quotas for your account and Region; requests per second and events per second are different units.
EventBridge rule patterns filter events after the event reaches a bus. Pipes filters select records from supported sources for a point-to-point flow. Source-side filtering is a separate choice: use it only when the producer or source service can actually avoid emitting or forwarding events you do not need. This distinction matters for both traffic and cost; a rule that filters an event after ingestion has not reduced the producer's publish calls.
Keep filters close to the consumer's subscription when consumers have different needs. Keep source-side filters when an upstream service has a supported native filter and no downstream consumer needs the excluded data. Test each filter against real examples, and account for events that match no rule or subscriber because those events will not reach a target.
Custom Event Bus - Classic does not retain events by default. Use an archive when you need to keep selected bus events and replay them later; an archive can select events with a pattern and has a configurable retention period. Replays return events to their original bus, can invoke targets again, and are not guaranteed to follow the order in which events entered the archive. Allow for archive delivery delay before starting a replay, and make replayed work safe to repeat.
Archive delivery can lag bus ingestion; AWS recommends waiting 10 minutes before replaying so the archive has time to receive events.
The newer Custom Event Bus has configurable built-in retention and lets subscribers start from retained events. Confirm which bus type your recovery plan uses: the resource model and replay mechanism differ. Archives incur charges, and replay can cause downstream processing and costs again, so estimate both storage and reprocessing using the current EventBridge pricing.
For regional recovery of custom events sent with PutEvents, Global endpoints route through a primary and secondary Region using a Route 53 health check. Failover takes time, and events may remain in the primary Region during an outage. Optional event replication can help validate configuration and return traffic to the primary automatically, but it adds cost. Confirm supported Regions, recovery objectives, and replication charges in the Global endpoints guide and pricing page before relying on this path.
Separate permission to publish from permission to administer rules or subscribers. Give producers permission to publish only to the required bus. Give EventBridge's target role only the action and resource needed by that target, and limit who can pass that role when configuring delivery. For cross-account use, apply the resource policy for a Classic bus or share the newer Custom Event Bus using its supported AWS Resource Access Manager controls.
Check both sides of a delivery path: a valid EventBridge rule or subscriber is not enough if the target policy or role cannot accept the event. Use least-privilege IAM policies and test them with the same account and Region structure used in production. The event bus permissions guide and the Custom Event Bus guide describe the distinct access models.
Reliable EventBridge designs start with the right feature and a clear event contract. Test patterns, process partial publish failures, expect retries and duplicates where the bus type allows them, and use target-level metrics to confirm delivery. Before scaling or designing recovery, check the quotas and pricing for the specific bus, pipe, scheduler, and target in your Regions.
For another view of testing across AWS service boundaries, continue with 10 Best Practices for End-to-End Testing AWS Apps.