Event-Driven AWS via SDK Best Practices

These are the defaults every EventBridge and Step Functions integration should set explicitly, not leave to chance.

Walk the list once now, then use it as a review checklist before shipping code that publishes events, wires rules and targets, or defines and runs a state machine via SDK.

How to Use This List

• Each item is a rule stated positively, with a one-line rationale.
• Groups run roughly in order of impact: event/schema design first, then bus/rule wiring, workflow type choice, error handling, security, and observability.
• Check the boxes against your own code as a quick audit.
• Revisit whenever you add a new event type, target, or state machine.

A - Event Design & Schema

• Version event detail schemas. Include a version or similarly named field in detail so consumers can tell old and new shapes apart as producers evolve.
• Use a stable, dotted Source. Conventions like orders.api make rules and audits easy to read; avoid free-form or changing source strings.
• Keep detail additive, not breaking. Add new fields rather than renaming or removing existing ones, so older rules and consumers keep working.
• Serialize Detail deliberately. It is a JSON string, not an object - build it with your language's JSON encoder, never hand-built strings.
• Check FailedEntryCount on every PutEvents call. A partial failure across a batch of entries does not raise an exception on its own.

B - Buses, Rules & Targets

• Use a custom bus to isolate an application's events. Keep your own rules from colliding with AWS-service traffic and other teams' events on the default bus.
• Test patterns before relying on them. Use TestEventPattern against a real sample event - a silent pattern mismatch means a rule never fires, with no error raised.
• Don't assume ordering across targets. All targets on a matched rule run independently and in parallel; route dependent, ordered work through Step Functions instead.
• Grant RoleArn only where the target type requires it. Step Functions and Kinesis targets need an assumable role; scope it to exactly that target.
• Remove targets before deleting a rule. DeleteRule fails while targets remain attached - clean them up in order.

Test a pattern before trusting it in production.

# --- Python (boto3) ---
import boto3
import json
 
events = boto3.client("events")
result = events.test_event_pattern(
    EventPattern=json.dumps({"source": ["orders.api"], "detail-type": ["OrderPlaced"]}),
    Event=json.dumps({
        "source": "orders.api", "detail-type": "OrderPlaced",
        "detail": {"orderId": "ord-1"}, "account": "111122223333",
        "region": "us-east-1", "time": "2026-07-24T00:00:00Z",
        "id": "abc", "resources": [],
    }),
)
print(result["Result"])   # True or False

// --- TypeScript (AWS SDK v3) ---
import { EventBridgeClient, TestEventPatternCommand } from "@aws-sdk/client-eventbridge";
 
const events = new EventBridgeClient({});
const result = await events.send(new TestEventPatternCommand({
  EventPattern: JSON.stringify({ source: ["orders.api"], "detail-type": ["OrderPlaced"] }),
  Event: JSON.stringify({
    source: "orders.api", "detail-type": "OrderPlaced",
    detail: { orderId: "ord-1" }, account: "111122223333",
    region: "us-east-1", time: "2026-07-24T00:00:00Z",
    id: "abc", resources: [],
  }),
}));
console.log(result.Result);   // true or false

C - Cross-Account & Cross-Region

• Grant permission before adding a cross-boundary rule. PutPermission on the destination bus must exist first, or routed events are rejected.
• Prefer aws:PrincipalOrgID over listing accounts. Authorize a whole organization once instead of maintaining a per-account principal list.
• Scope roles to the exact destination ARN, region included. A role permitted in one region is not automatically permitted for a same-service ARN elsewhere.
• Audit DescribeEventBus policies periodically. Remove stale PutPermission statements for accounts or workloads that no longer need access.
• Name targets by what they do, not where they are. Clear target Ids make multi-account/region fan-out easier to review later.

D - Choosing Standard vs Express

• Choose the workflow type deliberately, not by default. Standard for long-running, exactly-once, auditable processes; Express for high-volume, short, at-least-once tasks.
• Design Express states to be idempotent. At-least-once semantics mean a state may run more than once under some failure conditions.
• Don't plan to change type later. It is fixed at creation - pick correctly up front rather than migrating a live state machine's callers.
• Use StartSyncExecution only for Express. It is rejected on Standard machines; poll DescribeExecution there instead.
• Match duration to type. Anything that might exceed a few minutes belongs in Standard, not Express.

E - Error Handling

• Order Retry/Catch entries specific-to-general. The first matching ErrorEquals wins, so a States.ALL listed early shadows more specific handling after it.
• Add jitter on high-concurrency retries. Set JitterStrategy: "FULL" so many failing executions don't retry on a synchronized schedule.
• Preserve original input on Catch. Set ResultPath on a catcher so the caught error is merged in, not overwriting the state's prior input.
• Don't retry permission errors. States.Permissions failures need an IAM fix, not a Retry block.
• Bound MaxAttempts deliberately. Standard workflows bill per state transition, so unbounded retries have a direct cost.

F - Security & Permissions

• Scope execution roles to exact API actions. Grant only the specific actions each SDK integration or target actually calls, never a wildcard service action.
• Grant EventBridge's invoke role only what its targets need. A role used for PutTargets should not carry unrelated permissions.
• Verify newer service integrations before depending on them. For fast-moving services (AgentCore, S3 Vectors, and similar), check AWS's current supported-integration list rather than assuming coverage.
• Keep custom-bus resource policies reviewed. Cross-account permissions should be revisited as workloads change, not left indefinitely.
• Avoid embedding secrets in event detail or state input. Both can surface in logs and execution history - pass references instead.

G - Observability & Cost

• Enable CloudWatch Logs for Express workflows before you need them. Express has no console execution history - logging is the only way to debug it after the fact.
• Use Standard's execution history for auditability. GetExecutionHistory gives a full state-by-state trace for long-running, exactly-once processes.
• Check FailedEntryCount and execution status explicitly. Neither PutEvents nor StartExecution raises on a partial or eventual failure - you must inspect the result.
• Track state transitions as a cost signal for Standard. Retries and branching both add billed transitions; watch for workflows that fan out more than expected.
• Alarm on FAILED/TIMED_OUT executions. Route Step Functions execution-status events through EventBridge to a notification target instead of relying on manual checks.

FAQs

Related

• EventBridge & Step Functions: Events and Orchestration - the model these rules build on.
• Event Buses, Rules & Pattern Matching - group B in depth.
• Cross-Account & Cross-Region Event Routing - group C in depth.
• Step Functions State Machines: Standard vs Express - group D in depth.
• Error Handling & Retries in State Machines - group E in depth.
• Step Functions SDK Integrations (Including AgentCore & S3 Vectors) - group F's integration-verification point in depth.

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