Skip to Content
Cloud Engineering Academy
8. Messaging, Events & Microservices

Amazon EventBridge: buses, rules, schemas and Pipes

Route business events by content with Amazon EventBridge: event buses and rules, patterns and input transformers, target retries and dead-letter queues, archive and replay, the schema registry (and its .NET gap), EventBridge Pipes, and the new enhanced custom event bus, with .NET 10, CDK and Terraform.

intermediate⏱ 3 h 🟡 Low costDVA-C03SAA-C03

Assumes: .NET 10 LTS · AWS SDK for .NET v4 (AWSSDK.EventBridge 4.1.0.2) · Amazon.CDK.Lib 2.277.0 · Terraform AWS provider v6 · AWS CLI v2 · Region us-east-1. Verified against official sources on 2026-11-18.

Learning objectives

By the end of this lesson you can:

  • Explain what an event, an event bus, a rule and a target are, and how EventBridge differs from SNS and SQS.
  • Write event patterns that route on the content of an event (prefix, numeric ranges, anything-but, exists), and test them with the TestEventPattern API before deploying.
  • Configure target retries, dead-letter queues and input transformers, and explain exactly when an event is dropped.
  • Send events from .NET with PutEvents and handle its partial-failure responses correctly.
  • Turn on archive and replay, replay a day of events after fixing a consumer, and say why every consumer must be idempotent.
  • Use the schema registry, know that EventBridge does not generate C# code bindings, and plan for it.
  • Build a point-to-point integration with EventBridge Pipes (source, filter, enrichment, target) and say when a Pipe beats a rule.
  • Describe the enhanced custom event bus announced in September 2026, and which parts of this module still use the classic bus.

Prerequisites

Why this matters in banking

TransactionPosted is the most valuable event Harbourline produces. Notifications, Fraud, Rewards, Collections and the Data Platform all want it, each wants a different slice, and each team ships on its own timetable. Three things happen in real organisations without an event bus:

  1. Producers learn about consumers. The core banking team keeps a list of "who to call", and every new consumer is a change request to the producer.
  2. Contracts drift. A producer renames amount to amountMinor. Five consumers break on a Friday, and nobody can say which fields are really used.
  3. Bugs cannot be undone. A consumer had a rounding bug for six hours. The fix is easy; re-running the six hours is not, because the events are gone.

EventBridge answers each: rules route by content so producers stay ignorant of consumers, the schema registry records the contract, and archive and replay lets you re-send last Tuesday's events to a fixed consumer. The price is discipline. EventBridge is at-least-once, a replay delivers events a second time, and an event that has been dropped is hard to find. This lesson covers both the power and the discipline.

The idea in plain language

An event is a fact that already happened: "transaction T-1042 posted for £5,000". It is not a command ("send an SMS") and it is not addressed to anyone.

An event bus is a pipe you put events into. You attach rules to the bus. A rule has an event pattern ("only TransactionPosted events of 10,000 or more") and up to five targets (SQS queue, Lambda, SNS topic, Step Functions state machine, another bus, an HTTPS API and many more). When an event matches a rule, EventBridge delivers a copy to each of the rule's targets.

Analogy: Harbourline's head-office sorting clerk. Every envelope from every branch lands on one desk (the bus). The clerk has a rulebook: "anything marked mortgage over £500,000 goes to Underwriting; anything marked fraud goes to Security and also to Compliance". The branch never learns who got a copy. The clerk also photocopies yesterday's mail into a filing cabinet (the archive), so that if Underwriting loses a day's post, the clerk can send the copies again.

How it differs from SNS and SQS

SQSSNSEventBridge
ModelPull from a queuePush to subscribersPush to targets chosen by rules
RoutingNoneFilter policy on the subscriptionRule with a content-based pattern on the bus
Stores messagesYes, up to 14 daysNoNo, except in an archive you create
ReplayNoFIFO topics onlyYes, from an archive
Typical rateHugeHugeLarge but quota-limited (see below)
TransformationNoneNoneInput transformers; Pipes enrichment
Best atWork distributionFast fan-out to known subscribersMany-to-many routing between teams and services

In practice they combine. Harbourline's module project uses EventBridge to route, SNS to fan out, SQS to buffer. The rule of thumb from the first lesson stands: EventBridge and SNS push, so a queue goes behind every consumer that must not lose work.

What problem Amazon EventBridge solves

EventBridge is a serverless event router with a built-in contract catalogue and a replay buffer. It exists so that teams can publish and consume events across accounts and SaaS partners without building their own router, and without agreeing on a message broker.

Limits and defaults (checked 2026-11-18)

SettingValue
PutEvents per requestUp to 10 entries; the whole request must be under 1 MB (the per-event limit rose from 256 KB to 1 MB in January 2026; not every Region has it ⚠ VERIFY your Region)
PutEvents rate, us-east-110,000 requests per second (soft quota; other Regions lower)
Rule invocations, us-east-118,750 per second (soft quota); over the limit, deliveries are delayed, not dropped
Targets per rule5 (hard limit)
Rules per event bus300 (100 in af-south-1 and eu-south-1)
Event buses per account per Region100
Event pattern size2,048 characters
Target retry policy (default)Up to 24 hours and 185 attempts, exponential backoff with jitter
Archive retentionYou choose a number of days; default is indefinite
Concurrent replays10 per account per Region; replays are deleted after 90 days
API destinations3,000 per Region; 300 invocations per second per destination
Pipes target payload6 MB in the Pipe, but limited by the target: 1 MB for an event bus, 256 KB for Step Functions

Honest limitations

  • At-least-once, no ordering. Two events can arrive out of order and an event can arrive twice.
  • Events are dropped after retries are exhausted, unless a target has a dead-letter queue. EventBridge does not tell the producer.
  • Five targets per rule. Need more? Add rules, or target an SNS topic and fan out there.
  • No built-in storage. Without an archive, an event that reached no matching rule is gone. PutEvents returns success even then.
  • Not for very high-volume streams. Millions of small telemetry events per second belong in Kinesis or MSK.
  • No official .NET code bindings. Schema code bindings exist for Go, Java, Python and TypeScript only.

Microsoft / Azure comparison

You know (Microsoft/Azure)AWS equivalentWhat's different
Azure Event Grid topic and subscriptionsEventBridge bus and rulesClose match. EventBridge adds archive and replay, a schema registry and Pipes in the same product. Event Grid uses CloudEvents; EventBridge uses its own envelope (source, detail-type, detail)
Event Grid advanced filtersEvent patternsPatterns are JSON documents matched on any field, including nested ones in detail
Service Bus topic + rulesSNS + filter policy, or EventBridge rulesService Bus stores messages per subscription. EventBridge does not; give each consumer a queue
Logic Apps / Event Grid + Azure Functions glueEventBridge PipesA Pipe wires source, filter, enrichment and target with no glue code
Azure Functions timer trigger, Logic Apps recurrenceEventBridge SchedulerA managed scheduler for one-off and recurring invocations of many targets. Free tier of 14 million invocations a month
Event Grid dead-lettering to blob storageTarget dead-letter queue (SQS)A DLQ is per target, and must be an SQS queue
Azure Schema Registry (Event Hubs)EventBridge schema registryDiscovery infers schemas from live events. Code generation is not available for C#
Event Grid partner and system topicsAWS service events and partner event sourcesAWS services (S3, EC2, CodePipeline and others) emit events onto the default bus

Events and event patterns

The envelope

Every event on a bus has the same outer shape. You provide source, detail-type and detail; EventBridge adds the rest.

{
  "version": "0",
  "id": "5e8a3c2f-6a41-4b19-9f2e-0d9a4a1b7c10",
  "source": "harbourline.core-banking",
  "detail-type": "TransactionPosted",
  "account": "111122223333",
  "time": "2026-11-18T09:15:42Z",
  "region": "us-east-1",
  "resources": [],
  "detail": {
    "transactionId": "T-1042",
    "accountId": "ACC-0042",
    "customerId": "CUST-0001",
    "amount": 5000.00,
    "currency": "GBP",
    "type": "CARD_PURCHASE",
    "channels": ["sms", "email"]
  }
}

The id is unique per event but is not a business idempotency key: a replayed or retried delivery of the same event keeps the same id, which is useful, but two different publishes of the same business fact get different ids. Put your own stable key (transactionId) in detail.

Conventions that save pain later: source is a reverse-DNS or company.system name you control (never aws.*, which is reserved), detail-type is the event name in PascalCase and past tense, and detail carries identifiers and facts only. Keep names, full account numbers and balances out; consumers that need them fetch them.

Event patterns

A pattern is a JSON document shaped like the event. Every field in the pattern must match (AND); the values listed for a field are alternatives (OR).

MatchPattern fragmentMeaning
Exact"source": ["harbourline.core-banking"]Equal to the string
Several values"currency": ["GBP", "EUR"]Either
Prefix"type": [{"prefix": "CARD_"}]Starts with CARD_
Suffix"file": [{"suffix": ".pdf"}]Ends with .pdf
Case-insensitive"ccy": [{"equals-ignore-case": "gbp"}]GBP, gbp
Anything but"channel": [{"anything-but": "push"}]Everything except push
Numeric"amount": [{"numeric": [">=", 10000]}]Number comparison, also ranges: [">", 0, "<=", 5000]
Exists"promo": [{"exists": false}]The field is absent
Wildcard"name": [{"wildcard": "inv-*.pdf"}]Glob-style
IP range"ip": [{"cidr": "10.0.0.0/24"}]Address inside the range
Either of two fields"$or": [{"a": [1]}, {"b": [2]}]OR across different fields
Nested"detail": {"amount": [...]}Match inside detail

If the event field is an array (like channels), the pattern matches when any element matches.

Example: large GBP card payments only.

{
  "source": ["harbourline.core-banking"],
  "detail-type": ["TransactionPosted"],
  "detail": {
    "currency": ["GBP"],
    "type": [{ "prefix": "CARD_" }],
    "amount": [{ "numeric": [">=", 10000] }]
  }
}

Test patterns against the real service

Patterns have fiddly edge cases (numbers versus strings, arrays, missing fields). The TestEventPattern API takes a pattern and a sample event and tells you whether they match. It costs nothing and needs no bus, so put it in your unit tests. The sample code below wraps it.

Targets, retries and dead-letter queues

When an event matches a rule, EventBridge delivers to each target with its own retry policy. The defaults are generous: retry for up to 24 hours, up to 185 times, with exponential backoff and jitter. You can shorten both (MaximumEventAgeInSeconds between 60 seconds and 24 hours, MaximumRetryAttempts 0 to 185).

Two failure classes behave differently:

  • Retriable (target unavailable, throttled, a 5xx from an API destination): retried until the policy is exhausted.
  • Non-retriable (the target no longer exists, permissions removed): not retried.

When the policy is exhausted, or the error is non-retriable, the event is dropped, unless the target has a dead-letter queue. A DLQ is an SQS queue you attach per target. EventBridge needs permission to write to it; a missing DLQ permission is a quiet way to lose the evidence of a failure.

An input transformer reshapes what the target receives: pull fields out of the event with JSON paths and drop them into a template. Use it to give consumers a small, stable contract instead of the whole envelope.

Permissions work in two ways: for SQS, SNS, Lambda, CloudWatch Logs and other resource-policy targets, the target's own resource policy allows events.amazonaws.com (with a aws:SourceArn condition on the rule). For targets that need an IAM role (Step Functions, Kinesis, ECS tasks, API destinations), you give the rule an execution role. The IaC below does both.

Archive and replay

An archive copies events that match a pattern from one bus into storage, for a retention period you choose (or forever). A replay sends the archived events from a time range back to the same bus, optionally only to chosen rules.

What you need to know to use it safely, all from the documentation:

  • An archive belongs to one source bus and cannot be changed afterwards. You can have several archives per bus.
  • Events arrive in the archive with a small delay; wait about 10 minutes before replaying recent events.
  • A replay delivers events in one-minute steps by event time, so order within a minute is not preserved, and a replay is billed and throttled like PutEvents.
  • Each replayed event carries a replay-name field. EventBridge adds a managed rule so replays are not archived again, and you can use replay-name in a rule or in your code to tell replayed events from live ones.
  • You can replay only to the source bus, up to 10 replays at once per Region. Replays are deleted after 90 days, but the archive stays.
  • Replaying does not remove events from the archive: you can replay the same window repeatedly.

The consequence for design is simple: a replay is a controlled duplicate. Every consumer must be idempotent (the idempotency lesson shows how), and anything with an external side effect (an SMS, a payment) should check replay-name and the idempotency key before acting. In the module project the SMS consumer claims the event's transactionId in a DynamoDB table first, so a replayed day does not text anyone twice.

Retention is a data-protection decision

An archive keeps copies of your events for as long as you configure, in a place consumers' own retention rules do not reach. Archives are encrypted by default with an AWS owned key. Decide the retention period with your data-protection team, keep detail free of personal data, and remember that deleting a customer's data does not delete the copies in an archive.

Schema registry and discovery

The schema registry stores the shape of your events. There are three default registries: schemas for AWS service events, discovered schemas, and your own custom registries.

  • Schema discovery reads events passing through a bus and infers a schema (OpenAPI 3 or JSON Schema draft 4 format), versioning it as the events change. You switch it on per bus.
  • Custom schemas you write yourself or upload, which is the better habit for a contract between teams.
  • Code bindings generate typed classes from a schema in the console, in an IDE toolkit or through the API. The supported languages are Go, Java, Python and TypeScript. C# is not on the list ⚠ VERIFY on the current docs page.

For a .NET team that means: treat the registry as documentation and a change-detection tool, and own the C# contract yourself. Keep the event detail as a record in a shared NuGet package (the module project's TransactionPosted does this), and test it against the schema JSON with a schema validator in CI. Exporting custom schemas from the registry is not supported, so keep the source of truth in your repository and publish it to the registry from there.

Check discovery before you turn it on

Schema discovery inspects live events. Do not enable it on a bus whose events carry personal data until security and data protection have reviewed what it stores, and use custom schemas for sensitive contracts. ⚠ VERIFY what example values, if any, discovery keeps.

EventBridge Pipes

A Pipe is a managed, point-to-point integration: one source, an optional filter, an optional enrichment step and one target. It removes the glue Lambda you would otherwise write to poll a queue, call an API and forward the result.

StageOptions
SourceSQS queue, Kinesis stream, DynamoDB stream, Amazon MQ broker, Amazon MSK or self-managed Apache Kafka
Filter (optional)An event pattern on the source record. You are charged only for events that pass
Enrichment (optional)Lambda, Step Functions, API Gateway or an API destination, to add data before the target
TargetMany AWS targets: Lambda, Step Functions (Standard asynchronous only; Express sync or async), SQS, SNS standard topics, Kinesis, Firehose, an event bus in the same account and Region, API destinations, ECS tasks and more

Behaviour worth knowing:

  • If the source preserves order (Kinesis, DynamoDB streams, FIFO queues, Kafka), the Pipe keeps it from source to target.
  • The Pipe polls, batches, and deletes or checkpoints for you, and retries failed batches. For stream sources you configure retry attempts and a dead-letter destination.
  • The effective payload limit is the smaller of the Pipe's 6 MB and the target's: 256 KB for Step Functions, 1 MB for an event bus.
  • The Pipe uses its own IAM role: allow pipes.amazonaws.com to assume it, and grant read on the source and write on the target.
  • A Pipe cannot use a custom event bus of the new enhanced type as a target (see below). It can use a classic bus.
  • Price: about USD 0.40 per million requests ⚠ VERIFY, each 64 KB chunk counting as a request.

When to use which: a rule routes one event to many targets by content (many-to-many). A Pipe moves records from one source to one target with optional enrichment (point-to-point). Typical Pipes: SQS to Step Functions (the IaC below), DynamoDB stream to EventBridge bus, Kinesis to Lambda with a filter, MSK to an API destination.

EventBridge Scheduler (in one paragraph)

EventBridge Scheduler is a separate feature for time-based invocations: one-off ("charge this standing order at 06:00 on Friday") and recurring (cron and rate expressions), with time zones and retry policies, against a large set of targets. The free tier is 14 million invocations a month and beyond that it is about USD 1 per million ⚠ VERIFY. Use it instead of a cron-style rule when you have many one-off schedules, because rules are limited to 300 per bus.

The enhanced custom event bus (September 2026)

On 2026-09-24 AWS announced a new bus type, the enhanced custom event bus, built for organisation-wide use across many accounts. Existing buses now show in the console as Custom event bus – classic and keep working unchanged; the new one is a separate resource you adopt at your own pace. From the announcement:

Classic custom bus (this module's lab)Enhanced custom bus
RoutingRules and targetsSubscribers (filter, target, retry and DLQ in one resource)
Cross-accountBus-to-bus rules or resource policiesSharing through AWS Resource Access Manager
OrderingNoneOptional ordered delivery for events with the same EventGroupId
DuplicatesNoneOptional content-based deduplication (five-minute window)
TransformationInput transformersJSONata expressions
PricingPer eventThroughput based: ingress and egress per GB
AvailabilityEverywhere EventBridge runsA subset of Regions at launch (includes us-east-1) ⚠ VERIFY your Region
Pipes targetSupported (same account and Region)Not supported

Treat it as one to watch rather than a reason to rewrite. The whole module uses the classic bus, so the rules, archive and replay here are what you will meet in existing accounts. Before adopting the enhanced bus for a payment flow, verify in the current documentation how it handles archive and replay, schema discovery and Pipes, because those are the features this lesson relies on. ⚠ VERIFY

Architecture

Security-boundary view

Step-by-step implementation

Create the bus and an archive

Create a custom bus hl-m08gap-bus and an archive on it with retention of 7 days, filtering on source = harbourline.core-banking so you do not archive noise.

Write and test the pattern before the rule

Save the "large GBP card payments" pattern from earlier and a sample event. Run aws events test-event-pattern (or the MatchesAsync helper) and confirm true. Change the amount to 9,999 and confirm false.

Create the target queue, its DLQ and the permissions

Create hl-m08gap-large-transactions and hl-m08gap-rule-target-dlq. Give each a queue policy that lets events.amazonaws.com send, with an ArnEquals condition on the rule's ARN. Forgetting the DLQ's policy is the classic way to have a DLQ that stays empty while events are lost.

Create the rule with an input transformer and a retry policy

Attach the queue as the target. Use the transformer to send only transactionId, amount, currency and the event id. Set a retry window of two hours and 10 attempts, and the DLQ.

Publish, then break it on purpose

Send events with the .NET publisher. Confirm one lands in the queue and one (9,999) does not. Then delete the target queue's policy, publish again, and watch the event arrive in the DLQ instead of vanishing. Restore the policy.

Replay

Wait ten minutes, then start a replay of the last hour to the bus (CLI below). Confirm the replayed events carry replay-name, and that your idempotent consumer ignores them.

AWS Console instructions

Console → Amazon EventBridge → Buses → Event buses → Create event bus. Name it, leave the type as the classic custom event bus (the one this lesson uses; the console labels the new type "Custom event bus" and the old "Custom event bus – classic" ⚠ VERIFY the labels). Open the bus, Archives → Create archive: choose a retention period and paste an event pattern. Rules → Create rule: pick the bus, Rule with an event pattern, use the Event pattern form or paste JSON, and use Test pattern with a sample event. Choose the target; under Additional settings set the Retry policy, Dead-letter queue and Configure target input → Input transformer.

Schemas is its own item in the left menu: use Discover schemas on the bus, browse the discovered registry and Download code bindings for a supported language.

Pipes → Create pipe: choose source, then filter, enrichment and target, and let the console create the pipe's IAM role.

AWS CLI

export AWS_PROFILE=learn-sandbox AWS_REGION=us-east-1

# Bus, archive (kept 7 days).
aws events create-event-bus --name hl-m08gap-bus \
  --tags Key=Project,Value=cea-lab Key=Lab,Value=m08-messaging-services
BUS_ARN=$(aws events describe-event-bus --name hl-m08gap-bus --query Arn --output text)
aws events create-archive --archive-name hl-m08gap-archive --event-source-arn "$BUS_ARN" \
  --retention-days 7 --event-pattern '{"source":["harbourline.core-banking"]}'

# Test a pattern against a sample event BEFORE creating the rule.
cat > pattern.json <<'EOF'
{ "source": ["harbourline.core-banking"], "detail-type": ["TransactionPosted"],
  "detail": { "currency": ["GBP"], "amount": [{ "numeric": [">=", 10000] }] } }
EOF
cat > event.json <<'EOF'
{ "id": "1", "account": "111122223333", "source": "harbourline.core-banking", "time": "2026-11-18T09:15:42Z",
  "region": "us-east-1", "resources": [], "detail-type": "TransactionPosted",
  "detail": { "transactionId": "T-1042", "currency": "GBP", "amount": 12000 } }
EOF
aws events test-event-pattern --event-pattern file://pattern.json --event file://event.json

# Rule (the target is added with put-targets; see the IaC tabs for the full retry, DLQ and transformer settings).
aws events put-rule --name hl-m08gap-large-transactions --event-bus-name hl-m08gap-bus \
  --event-pattern file://pattern.json

# Publish one event. A zero FailedEntryCount is what to check, not the HTTP status.
aws events put-events --entries '[{"EventBusName":"hl-m08gap-bus","Source":"harbourline.core-banking","DetailType":"TransactionPosted","Detail":"{\"transactionId\":\"T-1042\",\"currency\":\"GBP\",\"amount\":12000}"}]' \
  --query '{failed:FailedEntryCount,entries:Entries}'

# Replay the last hour (wait about 10 minutes after the events were sent).
ARCHIVE_ARN=$(aws events describe-archive --archive-name hl-m08gap-archive --query ArchiveArn --output text)
aws events start-replay --replay-name hl-m08gap-replay-1 --event-source-arn "$ARCHIVE_ARN" \
  --destination "Arn=$BUS_ARN" \
  --event-start-time "$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
  --event-end-time "$(date -u -d '10 minutes ago' +%Y-%m-%dT%H:%M:%SZ)"
aws events describe-replay --replay-name hl-m08gap-replay-1 --query '{state:State,last:EventLastReplayedTime}'

# Schemas: discover from the bus, and (for supported languages) download code bindings.
aws schemas create-discoverer --source-arn "$BUS_ARN" --description "learning bus"
aws schemas list-schemas --registry-name discovered-schemas --query 'Schemas[].SchemaName'

Infrastructure as Code

The stack creates the bus and archive, the large-transactions queue and a rule-target DLQ, a content-filtered rule with an input transformer, retry policy and DLQ, and a Pipe from the queue to the payment-review state machine of the Step Functions lesson. The Pipe uses the L1 CfnPipe construct.

EventBusStack.cs
using Amazon.CDK;
using Amazon.CDK.AWS.Events;
using Amazon.CDK.AWS.IAM;
using Amazon.CDK.AWS.Pipes;
using Amazon.CDK.AWS.SQS;
using Constructs;
using EventTargets = Amazon.CDK.AWS.Events.Targets;

namespace Harbourline.Messaging.Infra;

public sealed class EventBusStackProps : StackProps
{
    /// <summary>ARN of the payment-review state machine the pipe starts (see WorkflowStack).</summary>
    public required string StateMachineArn { get; init; }
}

/// <summary>
/// A bus with an archive, a content-filtered rule with an input transformer and a target DLQ, and an EventBridge
/// Pipe (SQS source -> filter -> Step Functions target) for a point-to-point hand-off with no glue code.
/// </summary>
public sealed class EventBusStack : Stack
{
    public EventBusStack(Construct scope, string id, EventBusStackProps props) : base(scope, id, props)
    {
        var bus = new EventBus(this, "Bus", new EventBusProps { EventBusName = "hl-m08gap-bus" });

        // Archive: events kept 7 days so a fixed consumer can have a day replayed. Archives are encrypted with an AWS owned key by default.
        bus.Archive("Archive", new BaseArchiveProps
        {
            ArchiveName = "hl-m08gap-archive",
            Retention = Duration.Days(7),
            EventPattern = new EventPattern { Source = ["harbourline.core-banking"] },
        });

        var reviewQueue = new Queue(this, "LargeTransactionQueue", new QueueProps
        {
            QueueName = "hl-m08gap-large-transactions",
            Encryption = QueueEncryption.SQS_MANAGED,
            EnforceSSL = true,
        });
        var targetDlq = new Queue(this, "RuleTargetDlq", new QueueProps
        {
            QueueName = "hl-m08gap-rule-target-dlq",
            RetentionPeriod = Duration.Days(14),
            Encryption = QueueEncryption.SQS_MANAGED,
            EnforceSSL = true,
        });

        // Content-based routing: only TransactionPosted events of 10,000 or more, never the producer's concern.
        var rule = new Rule(this, "LargeTransactionRule", new RuleProps
        {
            RuleName = "hl-m08gap-large-transactions",
            EventBus = bus,
            EventPattern = new EventPattern
            {
                Source = ["harbourline.core-banking"],
                DetailType = ["TransactionPosted"],
                Detail = new Dictionary<string, object>
                {
                    ["amount"] = new[] { new Dictionary<string, object> { ["numeric"] = new object[] { ">=", 10000 } } },
                },
            },
        });

        rule.AddTarget(new EventTargets.SqsQueue(reviewQueue, new EventTargets.SqsQueueProps
        {
            // Input transformer: the consumer receives a small, stable contract instead of the whole envelope.
            Message = RuleTargetInput.FromObject(new Dictionary<string, object>
            {
                ["transactionId"] = EventField.FromPath("$.detail.transactionId"),
                ["amount"] = EventField.FromPath("$.detail.amount"),
                ["currency"] = EventField.FromPath("$.detail.currency"),
                ["eventId"] = EventField.FromPath("$.id"),
            }),
            DeadLetterQueue = targetDlq,
            RetryAttempts = 10,
            MaxEventAge = Duration.Hours(2),
        }));

        // ---- EventBridge Pipe: queue -> (filter) -> state machine. The pipe polls, batches and deletes for you.
        var pipeRole = new Role(this, "PipeRole", new RoleProps
        {
            AssumedBy = new ServicePrincipal("pipes.amazonaws.com"),
        });
        reviewQueue.GrantConsumeMessages(pipeRole);
        pipeRole.AddToPolicy(new PolicyStatement(new PolicyStatementProps
        {
            Actions = ["states:StartExecution"],
            Resources = [props.StateMachineArn],
        }));

        _ = new CfnPipe(this, "ReviewPipe", new CfnPipeProps
        {
            Name = "hl-m08gap-large-to-review",
            RoleArn = pipeRole.RoleArn,
            Source = reviewQueue.QueueArn,
            SourceParameters = new CfnPipe.PipeSourceParametersProperty
            {
                SqsQueueParameters = new CfnPipe.PipeSourceSqsQueueParametersProperty { BatchSize = 1 },
                FilterCriteria = new CfnPipe.FilterCriteriaProperty
                {
                    // Pipe filters see the SQS message: the JSON body is matched under "body".
                    Filters = [new CfnPipe.FilterProperty { Pattern = """{ "body": { "currency": ["GBP"] } }""" }],
                },
            },
            Target = props.StateMachineArn,
            TargetParameters = new CfnPipe.PipeTargetParametersProperty
            {
                // A Standard workflow can only be started asynchronously from a pipe.
                StepFunctionStateMachineParameters = new CfnPipe.PipeTargetStateMachineParametersProperty { InvocationType = "FIRE_AND_FORGET" },
                InputTemplate = """{ "paymentId": <$.body.transactionId>, "amount": <$.body.amount>, "recipients": [] }""",
            },
        });

        _ = new CfnOutput(this, "BusName", new CfnOutputProps { Value = bus.EventBusName });
    }
}

The module project's own stack, labs/m08-notification-system/infra/cdk/Harbourline.Notifications.Infra/NotificationStack.cs, uses the same building blocks: a bus hl-m08-events, a 7-day archive, a rule that targets an SNS topic with RetryAttempts = 20 and a two-hour MaxEventAge, and a target DLQ.

Complete code

The publisher below is what a .NET producer needs: batch to the 10-entry limit, read FailedEntryCount and each entry's ErrorCode, retry only the failures with jittered backoff, and hand back what is still unsent so the caller can park it. It is the missing half of the outbox pattern: the relay calls it and only marks outbox rows as sent when they come back confirmed.

dotnet add package AWSSDK.EventBridge --version 4.1.0.2
TransactionEventPublisher.cs
using System.Text.Json;
using Amazon.EventBridge;
using Amazon.EventBridge.Model;

namespace Harbourline.Messaging.Samples.EventBridge;

public sealed class TransactionEventPublisher(IAmazonEventBridge events, string busName, Func<int, TimeSpan>? backoff = null)
{
    public const string Source = "harbourline.core-banking";
    public const int MaxEntriesPerCall = 10;
    private const int MaxAttempts = 4;

    // Full jitter: a random delay between zero and an exponentially growing cap.
    private readonly Func<int, TimeSpan> _backoff = backoff
        ?? (attempt => TimeSpan.FromMilliseconds(Random.Shared.Next(0, 100 * (1 << attempt))));

    /// <summary>
    /// Sends events and retries ONLY the entries EventBridge rejected. PutEvents returns HTTP 200 even when some
    /// entries fail, so a status-code check is not enough: read FailedEntryCount and each entry's ErrorCode.
    /// Returns the details that still failed after every attempt (the caller parks them, e.g. in an outbox table).
    /// </summary>
    public async Task<IReadOnlyList<object>> PutAsync(
        string detailType, IEnumerable<object> details, CancellationToken ct = default)
    {
        var pending = details.ToList();

        for (var attempt = 1; attempt <= MaxAttempts && pending.Count > 0; attempt++)
        {
            var stillFailing = new List<object>();

            foreach (var chunk in pending.Chunk(MaxEntriesPerCall))
            {
                var response = await events.PutEventsAsync(new PutEventsRequest
                {
                    Entries = chunk.Select(d => new PutEventsRequestEntry
                    {
                        EventBusName = busName,
                        Source = Source,
                        DetailType = detailType,
                        Detail = JsonSerializer.Serialize(d, JsonSerializerOptions.Web),
                    }).ToList(),
                }, ct);

                if (response.FailedEntryCount == 0) continue;

                // Entries[i] answers request entry i: an ErrorCode means it failed, an EventId means it was accepted.
                for (var i = 0; i < chunk.Length; i++)
                {
                    if (!string.IsNullOrEmpty(response.Entries[i].ErrorCode)) stillFailing.Add(chunk[i]);
                }
            }

            pending = stillFailing;
            if (pending.Count > 0 && attempt < MaxAttempts) await Task.Delay(_backoff(attempt), ct);
        }

        return pending;
    }

    /// <summary>Asks EventBridge whether an event matches a pattern (the TestEventPattern API): the best unit test for a rule.</summary>
    public static async Task<bool> MatchesAsync(IAmazonEventBridge events, string pattern, string eventJson, CancellationToken ct = default)
    {
        var response = await events.TestEventPatternAsync(new TestEventPatternRequest { EventPattern = pattern, Event = eventJson }, ct);
        return response.Result ?? false;
    }
}

A unit test pins the behaviour that matters: HTTP 200 does not mean every entry was accepted, and only the rejected entry is resent.

SnsAndEventBridgeTests.cs (excerpt)
[Fact]
public async Task Only_rejected_entries_are_retried_and_http_200_is_not_trusted()
{
    var events = Substitute.For<IAmazonEventBridge>();
    var attempt = 0;
    events.PutEventsAsync(Arg.Any<PutEventsRequest>(), Arg.Any<CancellationToken>()).Returns(call =>
    {
        attempt++;
        var entries = call.Arg<PutEventsRequest>().Entries;
        if (attempt == 1)
            return new PutEventsResponse
            {
                FailedEntryCount = 1,
                Entries =
                [
                    new PutEventsResultEntry { EventId = "e-1" },
                    new PutEventsResultEntry { ErrorCode = "ThrottlingException", ErrorMessage = "Rate exceeded" },
                    new PutEventsResultEntry { EventId = "e-3" },
                ],
            };
        Assert.Single(entries); // the retry carries ONLY the failed entry
        return new PutEventsResponse { FailedEntryCount = 0, Entries = [new PutEventsResultEntry { EventId = "e-2" }] };
    });

    var publisher = new TransactionEventPublisher(events, "hl-bus", _ => TimeSpan.Zero);
    var unsent = await publisher.PutAsync("TransactionPosted", [new { id = 1 }, new { id = 2 }, new { id = 3 }],
        TestContext.Current.CancellationToken);

    Assert.Empty(unsent);
    Assert.Equal(2, attempt);
}

Code explained line by line

  1. Source = "harbourline.core-banking" is the contract's namespace. Rules, archives and consumers all key on it. Define it once as a constant, not as a string in five places.
  2. MaxEntriesPerCall = 10 matches the PutEvents batch limit. The loop slices pending items with Chunk(10).
  3. _backoff is full jitter: a random delay between zero and a cap that doubles each attempt. Jitter stops many producers retrying in lockstep after a throttle. The delegate is injectable so tests pass _ => TimeSpan.Zero.
  4. response.FailedEntryCount == 0 is the success test. PutEvents returns HTTP 200 even if some entries failed, and the Entries array always has the same length and order as the request.
  5. The inner for pairs chunk[i] with response.Entries[i] and keeps those with an ErrorCode. Only these go into the next attempt, so accepted events are not published twice by the retry.
  6. After MaxAttempts the method returns the leftovers instead of throwing. The caller decides: leave outbox rows unsent, park in a DLQ, alert.
  7. MatchesAsync wraps TestEventPattern. response.Result is a nullable bool in SDK v4, hence ?? false.

One more behaviour to remember: if you PutEvents to a bus name that does not exist, EventBridge returns HTTP 200 with a FailedEntryCount of 0 and the event goes nowhere. A typo in the bus name is a silent outage. Create buses in IaC and read the name from configuration, never retype it.

Security considerations

⚠ Learning shortcut — not for production

The lab bus accepts events from your own account only and the archive uses the default AWS owned key. A production bus that receives events from other accounts needs a bus resource policy that allows events:PutEvents only from named accounts or your AWS Organization (aws:PrincipalOrgID), a customer managed KMS key for the bus and archive where the data warrants it, and CloudTrail logging of bus and rule changes. A bus policy that allows * lets anyone on the internet who has an AWS account inject events into your payment flow.

⚠ Learning shortcut — not for production

The lab rule targets queues through resource policies. Production rules with IAM-role targets (Step Functions, ECS, Kinesis) should use a role per rule, scoped to the single target ARN, and set aws:SourceArn and aws:SourceAccount conditions on the role's trust policy to avoid the confused-deputy problem.

  • Producers. Allow events:PutEvents only on the specific bus ARN, and add a condition on events:source so a service can only publish its own source.
  • Event integrity. Consumers should treat source as a claim that only the IAM policy backs. Use the conditions above to make it true, and validate detail against the schema before acting.
  • Spoofing and injection. Anyone allowed to PutEvents can trigger every rule. Treat the right to publish TransactionPosted as equivalent to the right to post a transaction, and protect it accordingly.
  • Encryption. Events are encrypted in transit and at rest. Customer managed KMS keys are available for buses and archives; you then manage key policies, and that is another thing that can break delivery.
  • Auditing. Management events (rule and bus changes) go to CloudTrail by default. Recently, data-plane logging for EventBridge to CloudTrail was announced ⚠ VERIFY the scope before depending on it for audit.
  • Replay as an attack surface. events:StartReplay can re-trigger downstream side effects. Restrict it to a break-glass role and require a change ticket.
  • No personal data in events. Identifiers and facts only. This lesson does not make any system compliant with GDPR or PCI DSS; legal and security review decide that.

Banking use case

TransactionPosted on the Harbourline bus, as designed with this lesson:

RulePatternTarget
Notificationsdetail-type = TransactionPostedSNS topic, which fans out to the SMS and e-mail queues by channel
Large-payment reviewamount >= 10000SQS queue, then a Pipe starts the review workflow
Fraudcurrency != GBP or amount >= 5000 (two rules)Fraud queue
Rewardstype prefix CARD_Rewards queue
Data Platformall eventsFirehose to S3
Audit copyall eventsArchive, 7 days

A bug in Rewards is fixed on Wednesday. The team replays Tuesday's archive to the bus with the Rewards rule only, so other consumers do not see a second copy, and Rewards' idempotency table ignores the transactions it already credited.

Common mistakes

  • Treating PutEvents HTTP 200 as success. Failed entries are listed in the body. → Read FailedEntryCount and retry only the failures.
  • No DLQ on a target. The event is dropped after retries and nobody knows. → A DLQ on every target, with the permission statement, and an alarm on its depth.
  • A rule pattern that does not match numbers. "amount": [10000] does not match the string "10000", and string patterns do not match numbers. → Fix the producer's types and test with TestEventPattern.
  • Putting five unrelated targets on one rule. The limit is five, and failures are harder to attribute. → One rule per consumer.
  • Replaying to everyone. A replay without a rule filter re-triggers every consumer. → Name the rules in the replay.
  • Assuming order. → Put a sequence or timestamp in detail and handle out-of-order events (see Delivery guarantees and ordering).
  • Using id as the idempotency key. Two publishes of one business fact get different ids. → Use a stable business key.
  • Hard-coding the bus name. A typo silently drops events. → Configuration plus IaC.
  • Switching on schema discovery in production for sensitive data without review. → Use custom schemas.

Troubleshooting

SymptomLikely causeFix
Event published, nothing deliveredNo rule matched; wrong bus name; wrong source or detail-typeCheck bus name, then run test-event-pattern; look at the TriggeredRules and MatchedEvents metrics
MatchedEvents rises but the target gets nothingTarget permission missing or target deletedCheck the queue, topic or function resource policy; look at the FailedInvocations metric and the target DLQ
DLQ stays empty although the target is failingThe DLQ's own queue policy does not allow EventBridgeAdd sqs:SendMessage for events.amazonaws.com with the rule ARN condition
Numeric rule never matchesThe event carries the number as a string, or the pattern uses a stringAlign the types; use the numeric operator for numbers only
PutEvents returns FailedEntryCount > 0Throttling, entry too large or malformedRetry failed entries with jitter; split large events or store the payload in S3
ThrottlingException or delayed deliveriesAccount PutEvents or invocation quotaSmooth the producer, request a quota increase, add a queue
Replay delivered nothingReplayed too early (events not yet archived), or the time range or rule filter is wrongWait 10 minutes; check describe-replay and describe-archive counts (they reconcile only every 24 hours)
Consumer processes replayed events twiceNot idempotentIdempotency key table; check replay-name for side effects
Pipe "Invalid pipe target ARN"Targeting an enhanced custom busUse a classic bus as the Pipe target
Pipe to Step Functions fails with payload errorPayload over 256 KBSend an S3 pointer; shrink the enrichment output
Schema discovery shows nothingDiscoverer not on this bus, or no events sinceCreate the discoverer; publish test events

Cost and cleanup

Cost: credits (well under USD 1 if torn down the same day). Custom events on a classic bus cost about USD 1 per million, billed in 64 KB chunks, so a few hundred test events are a fraction of a cent. Delivery to a service in the same account is free. Archive processing is about USD 0.10 per GB and storage about USD 0.023 per GB-month, replays are billed like custom events, Pipes about USD 0.40 per million requests, and the Schema Registry is free (discovery has a 5-million-event monthly free allowance). All figures are from the pricing page examples ⚠ VERIFY on the EventBridge pricing page before estimating a production bill. Events from AWS services into the default bus are free.

Free alternative: the pattern matcher in the module project (labs/m08-notification-system/src/Harbourline.Notifications.Core/Routing/) and TestEventPattern calls need no bus. For a full offline run, use the simulator in that lab.

export AWS_PROFILE=learn-sandbox AWS_REGION=us-east-1

# Rules need their targets removed first.
aws events remove-targets --rule hl-m08gap-large-transactions --event-bus-name hl-m08gap-bus --ids $(aws events list-targets-by-rule --rule hl-m08gap-large-transactions --event-bus-name hl-m08gap-bus --query 'Targets[].Id' --output text)
aws events delete-rule --name hl-m08gap-large-transactions --event-bus-name hl-m08gap-bus
aws events delete-archive --archive-name hl-m08gap-archive
aws events delete-event-bus --name hl-m08gap-bus

# Schema discoverer (if you created one).
for d in $(aws schemas list-discoverers --query 'Discoverers[].DiscovererId' --output text); do aws schemas delete-discoverer --discoverer-id "$d"; done

# Pipe and queues.
aws pipes delete-pipe --name hl-m08gap-large-to-review 2>/dev/null
for q in hl-m08gap-large-transactions hl-m08gap-rule-target-dlq; do
  url=$(aws sqs get-queue-url --queue-name "$q" --query QueueUrl --output text 2>/dev/null) && aws sqs delete-queue --queue-url "$url"
done
rm -f pattern.json event.json

# If you deployed with IaC: cdk destroy HlM08Gap-Bus   |   terraform destroy

aws resourcegroupstaggingapi get-resources --tag-filters Key=Lab,Values=m08-messaging-services \
  --query 'ResourceTagMappingList[].ResourceARN'

Exercises

  • 🟢 Guided: Create the bus, the archive and the large-transactions rule. Use test-event-pattern to prove that an event of 12,000 GBP matches and 9,999 does not, then publish both with the .NET publisher and check the queue. Finally delete the queue policy, publish once more, and find the event in the DLQ.
  • 🟡 Challenge: Write a second rule, "Fraud", that matches events where the currency is not GBP or the amount is at least 5,000. Decide whether this is one rule with $or or two rules, and prove all four combinations with TestEventPattern. Add an input transformer that sends only transactionId and reason.
  • 🔴 Live problem: Ticket from the Rewards team: "On Tuesday, CardSettlement events were published at about 14:00 but Rewards never credited points. The rule shows MatchedEvents. Our queue is empty and its DLQ is empty. It's Thursday." Work out what could have happened, what evidence still exists, and how you would recover Tuesday's events without double-crediting anyone.

Assignment

Add eventbridge-design.md to your portfolio repository for one Harbourline event: the source and detail-type names, a JSON Schema for detail (identifiers only), three rules with patterns and TestEventPattern results, the target, retry policy and DLQ for each, an archive and replay procedure (including how consumers stay idempotent and which rule a replay is limited to), the bus resource policy for a second account, and the cost of 50 million events a month on a classic bus.

Solutions

Knowledge check

Interview questions

  • "EventBridge, SNS or SQS: how do you choose?" — SQS to hand work to one kind of consumer. SNS to fan out the same message quickly to known subscribers. EventBridge to route by content between teams and services, with archive and replay and schemas. And combine them: the bus routes, a topic fans out, a queue per consumer buffers.
  • "How do you stop events being lost?" — Read FailedEntryCount and retry failed entries from the producer (or use an outbox), put a DLQ and a permission on every rule target, alarm on DLQ depth, and keep an archive so a window can be replayed.
  • "What is the danger of replay?" — It is a deliberate duplicate. Consumers must be idempotent, side effects must check the idempotency key or replay-name, and the replay should be limited to the rule that needs it.
  • "How would you manage event contracts in .NET?" — A shared package with records for detail, a JSON Schema in the repository published to the registry, schema validation in CI, and additive-only changes. EventBridge does not generate C# bindings.
  • "What changed with the September 2026 enhanced bus?" — A new bus type with subscribers, ordered delivery, deduplication, JSONata transformation and organisation-wide sharing. Classic buses continue to work, and Pipes cannot target the new bus.

Certification practice

Completion checklist

  • I can describe event, bus, rule, target and pattern in a sentence each
  • I tested a pattern with TestEventPattern before using it in a rule
  • I attached a DLQ with a working policy to a target and saw an event land there
  • I replayed archived events and my consumer ignored the duplicates
  • I can explain why PutEvents HTTP 200 is not proof of success
  • I know EventBridge has no C# code bindings and what I do instead
  • I ran the cleanup and the tag check returned []

Key takeaways

  • Rules route by content, so producers never learn who consumes. At-least-once, no ordering, five targets per rule.
  • A target without a DLQ loses events silently after the retry window (24 hours, 185 attempts by default). PutEvents can return 200 with failed entries.
  • Archive and replay make bugs recoverable, but a replay is a duplicate: idempotent consumers, and limit the replay to the rule that needs it.
  • The schema registry documents the contract, but there are no C# bindings: own your typed contract and validate it in CI.
  • Pipes are the glue-free point-to-point option. The enhanced custom event bus (September 2026) is new: this module uses the classic bus.

Further reading

Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page