# AWS Events Reference AWS Events Reference An *event* indicates a change in an environment or service. For example: + Amazon EC2 generates an event when the state of an instance changes, such as from pending to running. + AWS CloudFormation generates an event when it creates, updates, or deletes a stack. + AWS CloudTrail publishes events when you make API calls. For a list of AWS services that generate events, see [Events](events.md). ## Using events to connect AWS services Using events Amazon EventBridge is a serverless service that uses events to connect application components together, making it easier for you to build scalable event-driven applications. Event-driven architecture is a style of building loosely-coupled software systems that work together by emitting and responding to events. Using EventBridge to deliver AWS events from one service to another enables you to create EDA applications. Here's how it works: Many AWS services generate and send events to the EventBridge default event bus. (An event bus is a router that receives events and delivers them to zero or more destinations, or *targets*.) Rules you specify for the event bus evaluate events as they arrive. Each rule checks whether an event matches the rule's *event pattern*. If the event does match, the event bus sends the event to the specified target(s). ![\[AWS services send events to the EventBridge default event bus. If the event matches a rule's event pattern, EventBridge sends the event to the targets specified for that rule.\]](http://docs.aws.amazon.com/eventbridge/latest/ref/images/eventbridge-integration-how-it-works.png) For more information, see [Event buses](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-bus.html) and [Rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html) in the *EventBridge User Guide*. # Event structure Event structure Events are represented as JSON objects, and they all have a similar structure, and the same top-level fields. These top-level fields contain the event's metadata, such as the source of the event, the account and region in which it occurred, and the time at which it occurred. For more information about event metadata, see [AWS service event metadata](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events-structure.html) in the *EventBridge User Guide*. The combination of the **source** and **detail-type** fields identify the service that has generated the event, and the type of event, respectively. For example, in the following event snippet, `source` identifies the originating AWS service as CloudFormation, while `detail-type` shows that the event represent a change in a stack's status. ``` { . . . "source": "aws.cloudformation", . . . "detail-type": "CloudFormation Stack Status Change", } } ``` The contents of the **detail** field are different depending on which service generated the event, and what the event is. If we examine the complete event, we can see the specific stack involved, and that the event was generated when its status became `CREATE_COMPLETE`. ``` { "version": "0", "source": "aws.cloudformation", "account": "123456789012", "id": "12345678-1234-1234-1234-111122223333", "region": "us-east-1", "detail-type": "CloudFormation Stack Status Change", "time": "2022-04-31T17:00:00Z", "resources": ["arn:aws:cloudformation:us-east-1:123456789012:stack/teststack"], "detail": { "stack-id": "arn:aws:cloudformation:us-west-1:123456789012:stack/teststack", "status-details": { "status": "CREATE_COMPLETE", "status-reason": "" } } } ``` Knowing the structure and fields present in an event enables you to create an event pattern to match against that event. For more information, see [Event patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html) in the *EventBridge User Guide* # AWS service event metadata Event metadata The following fields appear in all events delivered to an event bus, and comprise the event's *metadata*: ``` { "version": "0", "id": "UUID", "detail-type": "event name", "source": "event source", "account": "ARN", "time": "timestamp", "region": "region", "replay-name": "replay name", "resources": [ "ARN" ], "detail": { JSON object } } ``` **version** By default, this is set to 0 (zero) in all events. **id** A Version 4 UUID that's generated for every event. You can use `id` to trace events as they move through rules to targets. **detail-type** Identifies, in combination with the **source** field, the fields and values that appear in the **detail** field. Events that are delivered by CloudTrail have one of the following values for `detail-type`. For more information, see [AWS service events delivered via CloudTrail](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event-cloudtrail.html) in the *Amazon EventBridge User Guide*. + `AWS API Call via CloudTrail` + `AWS Console Signin via CloudTrail` + `AWS Console Action via CloudTrail` + `AWS Service Event via CloudTrail` + `AWS Insight via CloudTrail` **source** Identifies the service that generated the event. All events that come from AWS services begin with "aws." Customer-generated events can have any value here, as long as it doesn't begin with "aws." We recommend the use of Java package-name style reverse domain-name strings. **account** The 12-digit number identifying an AWS account. **time** The event timestamp, which can be specified by the service originating the event. If the event spans a time interval, the service can report the start time, so this value might be before the time the event is received. **region** Identifies the AWS Region where the event originated. **replay-name** A string representing the name of the replay. This field is present only for archived events that are resent to a target as part of a replay. For more information, see [Archiving and replaying events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-archive.html) in the *EventBridge User Guide*. **resources** A JSON array that contains ARNs that identify resources that are involved in the event. The service generating the event determines whether to include these ARNs. For example, Amazon EC2 instance state-changes include Amazon EC2 instance ARNs, Auto Scaling events include ARNs for both instances and Auto Scaling groups, but API calls with AWS CloudTrail do not include resource ARNs. **detail** A JSON object that contains information about the event. The service generating the event determines the content of this field. It can be `"{}"`. AWS API call events have detail objects with approximately 50 fields nested several levels deep. [PutEvents](https://docs.aws.amazon.com/AmazonCloudWatchEvents/latest/APIReference/API_PutEvents.html) accepts data in JSON format. For the JSON number (integer) data type, the constraints are: a minimum value of -9,223,372,036,854,775,808 and a maximum value of 9,223,372,036,854,775,807. **Example: Amazon EC2 instance state-change notification** The following event in Amazon EventBridge indicates an Amazon EC2 instance being terminated. ``` { "version": "0", "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718", "detail-type": "EC2 Instance State-change Notification", "source": "aws.ec2", "account": "111122223333", "time": "2017-12-22T18:43:48Z", "region": "us-west-1", "resources": [ "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0" ], "detail": { "instance-id": " i-1234567890abcdef0", "state": "terminated" } } ``` ## Minimum information needed for a valid custom event Minimum valid custom event When you create custom events they must include the following fields: + `detail` + `detail-type` + `source` ``` { "detail-type": "event name", "source": "event source", "detail": { } } ``` # Delivery level for AWS service events Event delivery level Each AWS service that generates events sends them to EventBridge as either *best effort* or *durable* delivery attempts. + *Best effort delivery* means that the service attempts to send all events to EventBridge, but in some rare cases an event might not be delivered. + *Durable delivery* means the service will successfully attempt to deliver events to EventBridge at least once. Once a valid event is delivered to EventBridge, EventBridge matches it against rules and then follows the retry policy and any dead-letter queue specified for the event target(s). For more information, see [Retrying event delivery](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rule-retry-policy.html) in the *EventBridge User Guide*.