Event Buses, Rules & Pattern Matching

Q: Do I need a custom event bus?

No. The default bus works for most use cases. A custom bus is worth creating when you want to isolate an application's rules from AWS-service events and other teams' traffic.

Q: How does array matching work in an event pattern?

Arrays are OR - "source": ["a", "b"] matches either. Multiple top-level keys are AND - all listed fields must match for the rule to fire.

Q: Can I match on numeric comparisons, not just exact values?

Yes, using content-based filters like {"numeric": [">", 100]}, {"prefix": "us-"}, or {"anything-but": ["cancelled"]} inside the pattern.

Q: Can I delete a rule that still has targets?

No, DeleteRule fails while targets remain attached. Call RemoveTargets with the target IDs first.

Every EventBridge integration is built from three calls: create or choose a bus, define a rule's pattern, and attach targets.

This page covers all three from both SDKs, plus the pattern-matching syntax that decides which events a rule actually fires on.

Recipe

Create a rule with an event pattern, then attach targets. Publish events; matching ones fan out to every attached target.

# --- Python (boto3) ---
import boto3
import json
 
events = boto3.client("events")
events.put_rule(
    Name="high-value-orders",
    EventPattern=json.dumps({
        "source": ["orders.api"],
        "detail-type": ["OrderPlaced"],
        "detail": {"total": [{"numeric": [">", 100]}]},
    }),
)
events.put_targets(
    Rule="high-value-orders",
    Targets=[{"Id": "review-queue", "Arn": "arn:aws:sqs:us-east-1:111122223333:order-review"}],
)

// --- TypeScript (AWS SDK v3) ---
import { EventBridgeClient, PutRuleCommand, PutTargetsCommand } from "@aws-sdk/client-eventbridge";
 
const events = new EventBridgeClient({});
await events.send(new PutRuleCommand({
  Name: "high-value-orders",
  EventPattern: JSON.stringify({
    source: ["orders.api"],
    "detail-type": ["OrderPlaced"],
    detail: { total: [{ numeric: [">", 100] }] },
  }),
}));
await events.send(new PutTargetsCommand({
  Rule: "high-value-orders",
  Targets: [{ Id: "review-queue", Arn: "arn:aws:sqs:us-east-1:111122223333:order-review" }],
}));

When to reach for this:

Several parts of your system need to react to the same class of event without knowing about each other.
You want AWS to filter events for you instead of every consumer inspecting and discarding irrelevant ones.
Targets are independent actions (notify, log, enqueue), not a dependent multi-step process.
You need to isolate one application's events from unrelated traffic on the account's default bus.

Working Example

Create a custom bus, a rule scoped to it, and two independent targets - a queue and a Step Functions workflow.

# --- Python (boto3) ---
import boto3
import json
 
events = boto3.client("events")
 
bus = events.create_event_bus(Name="orders-bus")
 
events.put_rule(
    Name="order-placed-rule",
    EventBusName="orders-bus",
    EventPattern=json.dumps({
        "source": ["orders.api"],
        "detail-type": ["OrderPlaced"],
    }),
    State="ENABLED",
)
 
events.put_targets(
    Rule="order-placed-rule",
    EventBusName="orders-bus",
    Targets=[
        {
            "Id": "audit-queue",
            "Arn": "arn:aws:sqs:us-east-1:111122223333:order-audit",
        },
        {
            "Id": "start-fulfillment",
            "Arn": "arn:aws:states:us-east-1:111122223333:stateMachine:FulfillOrder",
            "RoleArn": "arn:aws:iam::111122223333:role/eventbridge-invoke-sfn",
        },
    ],
)

// --- TypeScript (AWS SDK v3) ---
import {
  EventBridgeClient,
  CreateEventBusCommand,
  PutRuleCommand,
  PutTargetsCommand,
} from "@aws-sdk/client-eventbridge";
 
const events = new EventBridgeClient({});
 
await events.send(new CreateEventBusCommand({ Name: "orders-bus" }));
 
await events.send(new PutRuleCommand({
  Name: "order-placed-rule",
  EventBusName: "orders-bus",
  EventPattern: JSON.stringify({
    source: ["orders.api"],
    "detail-type": ["OrderPlaced"],
  }),
  State: "ENABLED",
}));
 
await events.send(new PutTargetsCommand({
  Rule: "order-placed-rule",
  EventBusName: "orders-bus",
  Targets: [
    {
      Id: "audit-queue",
      Arn: "arn:aws:sqs:us-east-1:111122223333:order-audit",
    },
    {
      Id: "start-fulfillment",
      Arn: "arn:aws:states:us-east-1:111122223333:stateMachine:FulfillOrder",
      RoleArn: "arn:aws:iam::111122223333:role/eventbridge-invoke-sfn",
    },
  ],
}));

What this demonstrates:

A custom bus (orders-bus) scopes the rule away from the account's default bus and any unrelated events on it.
State: "ENABLED" (the default) means the rule is live immediately; set "DISABLED" to stage it without firing.
Two targets on one rule both fire independently when an event matches - a queue for audit, and a state machine for the real work.
The Step Functions target needs RoleArn so EventBridge is authorized to call StartExecution on your behalf.

An EventPattern is JSON matched structurally against an event's top-level fields (source, detail-type, account, region) and anything inside detail. Every array is an implicit OR: "source": ["orders.api", "billing.api"] matches either. Matching is AND across fields: an event must satisfy every key present in the pattern.

Content filters go beyond exact match. Common operators:

{
  "detail": {
    "total": [{ "numeric": [">", 100] }],
    "status": [{ "anything-but": ["cancelled"] }],
    "region": [{ "prefix": "us-" }]
  }
}

numeric compares numbers, anything-but excludes values, prefix matches string prefixes, and plain arrays do exact-value matching. A pattern with no operator on a field requires an exact match against one of the listed values.

Default Bus vs Custom Bus

The default bus already exists per account and per region, and it is the one AWS services publish to automatically (for example, EC2 state-change notifications). A custom bus is created with CreateEventBus purely for organizational isolation - your own application's events live there, separate from AWS-service noise and other teams' rules. Rules, targets, and permissions are all scoped per bus, so nothing on orders-bus interferes with anything on default.

Targets Run Independently

PutTargets can attach up to five targets per rule (more with a service quota increase). Every attached target that a rule matches is invoked - there is no sequencing, no shared state, and no guarantee one finishes before another starts. If a target fails, EventBridge retries that target on its own retry policy; other targets on the same rule are unaffected.

Managing Rules and Targets

# --- Python (boto3) ---
import boto3
 
events = boto3.client("events")
 
for page in events.get_paginator("list_rules").paginate(EventBusName="orders-bus"):
    for rule in page["Rules"]:
        print(rule["Name"], rule["State"])
 
events.remove_targets(Rule="order-placed-rule", EventBusName="orders-bus", Ids=["audit-queue"])
events.delete_rule(Name="order-placed-rule", EventBusName="orders-bus")

// --- TypeScript (AWS SDK v3) ---
import {
  EventBridgeClient,
  paginateListRules,
  RemoveTargetsCommand,
  DeleteRuleCommand,
} from "@aws-sdk/client-eventbridge";
 
const events = new EventBridgeClient({});
 
for await (const page of paginateListRules({ client: events }, { EventBusName: "orders-bus" })) {
  for (const rule of page.Rules ?? []) console.log(rule.Name, rule.State);
}
 
await events.send(new RemoveTargetsCommand({ Rule: "order-placed-rule", EventBusName: "orders-bus", Ids: ["audit-queue"] }));
await events.send(new DeleteRuleCommand({ Name: "order-placed-rule", EventBusName: "orders-bus" }));

Remove targets before deleting a rule - DeleteRule fails if targets are still attached.

Gotchas

Pattern typo matches nothing, silently. A misspelled key or wrong nesting means the rule simply never fires, with no error at PutRule time. Fix: test the pattern with TestEventPattern against a sample event before relying on it.
Forgetting EventBusName on a custom bus. Rule and target calls default to the default bus if omitted. Fix: pass EventBusName consistently across PutRule, PutTargets, and PutEvents.
Deleting a rule with targets still attached. DeleteRule rejects the call. Fix: call RemoveTargets (or RemoveTargets with Force, depending on target type) first.
Expecting ordering between targets. All targets on a matched rule fire independently and in parallel. Fix: if steps depend on each other, route to a single Step Functions target instead of multiple raw targets.
Missing RoleArn on a Step Functions or Kinesis target. The target silently fails to invoke. Fix: attach an IAM role EventBridge can assume with permission to invoke that target.
Assuming detail fields are typed. Pattern matching on detail compares against whatever type the JSON actually contains (string vs number). Fix: keep event producers consistent about field types.

Alternatives

Alternative	Use When	Don't Use When
EventBridge rule + targets	Independent consumers reacting to the same event	Consumers must run in a dependent order
SNS topic	Simple fan-out with no content-based filtering needed	You need to filter on nested JSON fields
SQS direct integration	A single known consumer polling a queue	Multiple decoupled consumers should react
Step Functions as the sole entry point	The reaction is itself a multi-step, ordered process	A single independent action is all that's needed

FAQs

Do I need a custom event bus?

No. The default bus works for most use cases. A custom bus is worth creating when you want to isolate an application's rules from AWS-service events and other teams' traffic.

How does array matching work in an event pattern?

Arrays are OR - "source": ["a", "b"] matches either. Multiple top-level keys are AND - all listed fields must match for the rule to fire.

Can I match on numeric comparisons, not just exact values?

Yes, using content-based filters like {"numeric": [">", 100]}, {"prefix": "us-"}, or {"anything-but": ["cancelled"]} inside the pattern.

How many targets can one rule have?

Up to five by default, and all of them are invoked independently when the rule matches - there is no ordering guarantee between them.

Why isn't my rule firing?

Almost always a pattern mismatch - wrong bus, a typo in a key, or a value that doesn't match any array entry. Use TestEventPattern against a real sample event to debug it before assuming EventBridge itself is broken.

Can I delete a rule that still has targets?

No, DeleteRule fails while targets remain attached. Call RemoveTargets with the target IDs first.

EventBridge & Step Functions: Events and Orchestration - the conceptual split between the two services.
Cross-Account & Cross-Region Event Routing - extending buses and rules across boundaries.
Event-Driven AWS via SDK Best Practices - defaults for rules, targets, and permissions.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

This page covers all three from both SDKs, plus the pattern-matching syntax that decides which events a rule actually fires on.

Recipe

Create a rule with an event pattern, then attach targets. Publish events; matching ones fan out to every attached target.

# --- Python (boto3) ---
import boto3
import json
 
events = boto3.client("events")
events.put_rule(
    Name="high-value-orders",
    EventPattern=json.dumps({
        "source": ["orders.api"],
        "detail-type": ["OrderPlaced"],
        "detail": {"total": [{"numeric": [">", 100]}]},
    }),
)
events.put_targets(
    Rule="high-value-orders",
    Targets=[{"Id": "review-queue", "Arn": "arn:aws:sqs:us-east-1:111122223333:order-review"}],
)

// --- TypeScript (AWS SDK v3) ---
import { EventBridgeClient, PutRuleCommand, PutTargetsCommand } from "@aws-sdk/client-eventbridge";
 
const events = new EventBridgeClient({});
await events.send(new PutRuleCommand({
  Name: "high-value-orders",
  EventPattern: JSON.stringify({
    source: ["orders.api"],
    "detail-type": ["OrderPlaced"],
    detail: { total: [{ numeric: [">", 100] }] },
  }),
}));
await events.send(new PutTargetsCommand({
  Rule: "high-value-orders",
  Targets: [{ Id: "review-queue", Arn: "arn:aws:sqs:us-east-1:111122223333:order-review" }],
}));

When to reach for this:

Several parts of your system need to react to the same class of event without knowing about each other.
You want AWS to filter events for you instead of every consumer inspecting and discarding irrelevant ones.
Targets are independent actions (notify, log, enqueue), not a dependent multi-step process.
You need to isolate one application's events from unrelated traffic on the account's default bus.

Working Example

Create a custom bus, a rule scoped to it, and two independent targets - a queue and a Step Functions workflow.

# --- Python (boto3) ---
import boto3
import json
 
events = boto3.client("events")
 
bus = events.create_event_bus(Name="orders-bus")
 
events.put_rule(
    Name="order-placed-rule",
    EventBusName="orders-bus",
    EventPattern=json.dumps({
        "source": ["orders.api"],
        "detail-type": ["OrderPlaced"],
    }),
    State="ENABLED",
)
 
events.put_targets(
    Rule="order-placed-rule",
    EventBusName="orders-bus",
    Targets=[
        {
            "Id": "audit-queue",
            "Arn": "arn:aws:sqs:us-east-1:111122223333:order-audit",
        },
        {
            "Id": "start-fulfillment",
            "Arn": "arn:aws:states:us-east-1:111122223333:stateMachine:FulfillOrder",
            "RoleArn": "arn:aws:iam::111122223333:role/eventbridge-invoke-sfn",
        },
    ],
)

// --- TypeScript (AWS SDK v3) ---
import {
  EventBridgeClient,
  CreateEventBusCommand,
  PutRuleCommand,
  PutTargetsCommand,
} from "@aws-sdk/client-eventbridge";
 
const events = new EventBridgeClient({});
 
await events.send(new CreateEventBusCommand({ Name: "orders-bus" }));
 
await events.send(new PutRuleCommand({
  Name: "order-placed-rule",
  EventBusName: "orders-bus",
  EventPattern: JSON.stringify({
    source: ["orders.api"],
    "detail-type": ["OrderPlaced"],
  }),
  State: "ENABLED",
}));
 
await events.send(new PutTargetsCommand({
  Rule: "order-placed-rule",
  EventBusName: "orders-bus",
  Targets: [
    {
      Id: "audit-queue",
      Arn: "arn:aws:sqs:us-east-1:111122223333:order-audit",
    },
    {
      Id: "start-fulfillment",
      Arn: "arn:aws:states:us-east-1:111122223333:stateMachine:FulfillOrder",
      RoleArn: "arn:aws:iam::111122223333:role/eventbridge-invoke-sfn",
    },
  ],
}));

What this demonstrates:

A custom bus (orders-bus) scopes the rule away from the account's default bus and any unrelated events on it.
State: "ENABLED" (the default) means the rule is live immediately; set "DISABLED" to stage it without firing.
Two targets on one rule both fire independently when an event matches - a queue for audit, and a state machine for the real work.
The Step Functions target needs RoleArn so EventBridge is authorized to call StartExecution on your behalf.

Deep Dive

Event Pattern Matching

Content filters go beyond exact match. Common operators:

{
  "detail": {
    "total": [{ "numeric": [">", 100] }],
    "status": [{ "anything-but": ["cancelled"] }],
    "region": [{ "prefix": "us-" }]
  }
}

Default Bus vs Custom Bus

Targets Run Independently

Managing Rules and Targets

# --- Python (boto3) ---
import boto3
 
events = boto3.client("events")
 
for page in events.get_paginator("list_rules").paginate(EventBusName="orders-bus"):
    for rule in page["Rules"]:
        print(rule["Name"], rule["State"])
 
events.remove_targets(Rule="order-placed-rule", EventBusName="orders-bus", Ids=["audit-queue"])
events.delete_rule(Name="order-placed-rule", EventBusName="orders-bus")

// --- TypeScript (AWS SDK v3) ---
import {
  EventBridgeClient,
  paginateListRules,
  RemoveTargetsCommand,
  DeleteRuleCommand,
} from "@aws-sdk/client-eventbridge";
 
const events = new EventBridgeClient({});
 
for await (const page of paginateListRules({ client: events }, { EventBusName: "orders-bus" })) {
  for (const rule of page.Rules ?? []) console.log(rule.Name, rule.State);
}
 
await events.send(new RemoveTargetsCommand({ Rule: "order-placed-rule", EventBusName: "orders-bus", Ids: ["audit-queue"] }));
await events.send(new DeleteRuleCommand({ Name: "order-placed-rule", EventBusName: "orders-bus" }));

Remove targets before deleting a rule - DeleteRule fails if targets are still attached.

Gotchas

Pattern typo matches nothing, silently. A misspelled key or wrong nesting means the rule simply never fires, with no error at PutRule time. Fix: test the pattern with TestEventPattern against a sample event before relying on it.
Forgetting EventBusName on a custom bus. Rule and target calls default to the default bus if omitted. Fix: pass EventBusName consistently across PutRule, PutTargets, and PutEvents.
Deleting a rule with targets still attached. DeleteRule rejects the call. Fix: call RemoveTargets (or RemoveTargets with Force, depending on target type) first.
Expecting ordering between targets. All targets on a matched rule fire independently and in parallel. Fix: if steps depend on each other, route to a single Step Functions target instead of multiple raw targets.
Missing RoleArn on a Step Functions or Kinesis target. The target silently fails to invoke. Fix: attach an IAM role EventBridge can assume with permission to invoke that target.
Assuming detail fields are typed. Pattern matching on detail compares against whatever type the JSON actually contains (string vs number). Fix: keep event producers consistent about field types.

Alternatives

Alternative	Use When	Don't Use When
EventBridge rule + targets	Independent consumers reacting to the same event	Consumers must run in a dependent order
SNS topic	Simple fan-out with no content-based filtering needed	You need to filter on nested JSON fields
SQS direct integration	A single known consumer polling a queue	Multiple decoupled consumers should react
Step Functions as the sole entry point	The reaction is itself a multi-step, ordered process	A single independent action is all that's needed

FAQs

Do I need a custom event bus?

No. The default bus works for most use cases. A custom bus is worth creating when you want to isolate an application's rules from AWS-service events and other teams' traffic.

How does array matching work in an event pattern?

Arrays are OR - "source": ["a", "b"] matches either. Multiple top-level keys are AND - all listed fields must match for the rule to fire.

Can I match on numeric comparisons, not just exact values?

Yes, using content-based filters like {"numeric": [">", 100]}, {"prefix": "us-"}, or {"anything-but": ["cancelled"]} inside the pattern.

How many targets can one rule have?

Up to five by default, and all of them are invoked independently when the rule matches - there is no ordering guarantee between them.

Why isn't my rule firing?

Can I delete a rule that still has targets?

No, DeleteRule fails while targets remain attached. Call RemoveTargets with the target IDs first.

EventBridge & Step Functions: Events and Orchestration - the conceptual split between the two services.
Cross-Account & Cross-Region Event Routing - extending buses and rules across boundaries.
Event-Driven AWS via SDK Best Practices - defaults for rules, targets, and permissions.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Event Buses, Rules & Pattern Matching

Buscar en la documentación

Event Buses, Rules & Pattern Matching