Event sources for a Custom Event Bus
An event source ingests events from an Amazon service or a SaaS partner onto a Custom Event Bus. You create it
with CreateEventSource, naming a destination bus and one origin, for example aws.s3,
and EventBridge delivers events from the origin to the bus. Your own applications publish to the bus directly, so you
need an event source only for events you do not produce yourself.
Ingested events arrive on the destination bus in the EventBridge envelope, with content type
application/eventbridge+json. The event data holds the envelope fields: source,
detail-type, account, time, region,
resources, and detail. EventBridge also sets the aws:Source and
aws:DetailType system metadata fields from the envelope's source and
detail-type. See Event structure: data, metadata, and system metadata.
How the events are moved
When you create an event source, EventBridge creates a managed rule and a target in your account, on your
Custom Event Bus - Classic, and they carry events from the origin to your Custom Event Bus. Both appear in your account
with ManagedBy set to events.amazonaws.com. You do not manage them; deleting or
revoking the event source removes them. The events therefore still appear in the Custom Event Bus - Classic's metrics.
Amazon service event sources
An Amazon service event source ingests the events that one Amazon service, such as aws.s3 or
aws.ec2, emits for your account. By default every event from that service arrives on the bus;
to narrow that down, add a Pattern. The following example creates an event source that admits
only Amazon S3 Object Created events.
aws eventsv2 create-event-source \ --name s3-object-created \ --event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef \ --configuration '{"AwsServiceEventsConfiguration":{"AwsService":"aws.s3","Pattern":"{\"detail-type\":[\"Object Created\"]}"}}'
The event source's pattern decides what crosses onto the bus. A subscriber's filter decides what that
subscriber receives from the events flowing through the bus; see Filtering events for a subscriber.
Write the pattern in EventBridge event pattern syntax (Amazon EventBridge event patterns), and EventBridge evaluates it
against the envelope. Leave the source key and the top-level account and
region keys out of the pattern: EventBridge adds those conditions itself, from your account and Region
and the service you selected, and rejects a pattern that supplies them.
Partner event sources
A partner event source ingests the events a SaaS partner sends to your account. Before you create one,
the partner must offer a partner event source to your account (see Receiving events from a SaaS partner with Amazon EventBridge), and that
source must be in the PENDING state. The following example creates an event source for
it.
aws eventsv2 create-event-source \ --name example-partner-events \ --event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef \ --configuration '{"PartnerEventsConfiguration":{"PartnerEventSourceArn":"arn:aws:events:us-east-1::event-source/aws.partner/example.com/12345"}}'
When you create the event source, EventBridge creates a managed partner event bus (a Custom Event Bus - Classic) in your
account to activate the partner source. When you delete the event source, EventBridge deletes that bus and returns
the partner source to PENDING. To encrypt that bus with a customer managed key, set
PartnerBusKmsKeyIdentifier to a key in your account and Region; otherwise EventBridge uses an Amazon
owned key.
Dead-letter queue
To capture events that fail to reach the bus, set OnFailureConfiguration.Arn to a standard
Amazon SQS queue in your account and Region; a FIFO queue is rejected. Messages arrive on the queue from the
events.amazonaws.com service principal, not from a role you supply, so grant that principal
sqs:SendMessage in the queue's resource policy.
{ "Effect": "Allow", "Principal": { "Service": "events.amazonaws.com" }, "Action": "sqs:SendMessage", "Resource": "arn:aws:sqs:us-east-1:111122223333:my-event-source-dlq", "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333" } } }
A partner event source sends to the queue under two source ARNs: the managed rule, for delivery
failures, and the managed partner event bus, for encryption failures. A policy that conditions on
aws:SourceArn must allow both.
Permissions
To create an event source on a bus in another account, the bus owner must grant you
events:CreateEventSource, through an Amazon RAM share
(AWSRAMEventBridgeEventBusV2EventSourceAccess or FullAccess) or with a
PutResourcePolicy statement on the bus. The events:source condition key carries the
Amazon service name or the partner event source name, so a bus owner can allow or deny specific origins. See
Sharing a Custom Event Bus with other accounts.
To encrypt the managed partner event bus, your identity needs kms:DescribeKey and
kms:Decrypt on the key you name in PartnerBusKmsKeyIdentifier; without them,
CreateEventSource fails with AccessDeniedException.
{ "Effect": "Allow", "Action": ["kms:DescribeKey", "kms:Decrypt"], "Resource": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" }
If another account owns the destination bus and encrypts it with a customer managed key, that key's policy must also admit your account; otherwise create, update, and describe of the event source fail.
Subscribing to ingested events
To match Amazon service or partner events on a subscriber, filter on the aws:Source system
metadata field. EventBridge writes this field and no publish call can set a value that begins with
aws., so a match on its value is the only match that proves the origin of an event. For Amazon
service events, match the service name; for partner events, match the partner event source name.
{ "Scope": "SYSTEM_METADATA", "Pattern": "{\"aws:Source\":[\"aws.s3\"]}" } { "Scope": "SYSTEM_METADATA", "Pattern": "{\"aws:Source\":[{\"prefix\":\"aws.partner/example.com\"}]}" }
To filter on the event content, add a DATA filter. The envelope carries the content under
detail.
{ "Scope": "DATA", "Pattern": "{\"detail\":{\"bucket\":{\"name\":[\"amzn-s3-demo-bucket\"]}}}" }
The event data also carries source and detail-type, and any publisher can write
those values into a payload, so they do not prove the origin. Match aws:Source by value, not by
presence: a direct PutEvents call also sets aws:Source, from its own
Source, which never starts with aws..
Permanently stopping an event source
The bus owner can permanently stop an event source from ingesting by calling RevokeResource
with its ARN; see Revoking a subscriber or an event source. A revoked event source cannot be restored.
Revocation covers the one resource you name, so pair it with a bus resource policy that stops the same
account from creating another. To block the account from creating any event source on the bus:
{ "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::444455556666:root" }, "Action": "events:CreateEventSource", "Resource": "arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef" }
To block one origin while allowing others, condition the deny on events:source.
{ "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::444455556666:root" }, "Action": "events:CreateEventSource", "Resource": "arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef", "Condition": { "StringEquals": { "events:source": "aws.partner/example.com/12345" } } }
Confirming that events cross onto the bus
Two sets of metrics show whether ingested events reach the Custom Event Bus. The managed rule reports the
usual rule metrics in your account, under AWS/Events. The destination bus's publish metrics
carry an EventSource dimension, which gives a per-event-source breakdown of inbound traffic; see
Observability for the Custom Event Bus: metrics, logs, and CloudTrail.
When a subscriber carries events from one Custom Event Bus to another across accounts, Amazon service and
partner events keep their aws:Source and aws:DetailType as long as the event's
structure and content stay intact. EventBridge authorizes their arrival on the destination bus with
events:PutEvents, so the destination bus's resource policy must grant that action to the
forwarding role. Events your applications published take events:PutRawEvents, so a stream that
mixes both needs both actions; see Event bus target: bus to bus.