Amazon EventBridge

(1)

Amazon EventBridge

API Reference

API Version 2015-10-07

(2)

Amazon EventBridge: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Amazon EventBridge API Reference

Amazon EventBridge is a serverless event bus service that makes it easy to connect your applications with data from a variety of sources.

EventBridge was formerly known as Amazon CloudWatch Events. EventBridge expands on the capabilities of CloudWatch Events, adding support for processing events from software-as-a-service (SaaS) partner applications and making it easier for you to process events from your own applications.

EventBridge starts with the same set of APIs as CloudWatch Events and adds new APIs. EventBridge also oﬀers more functionality both in the API and on the console.

Use the following links to get started using the EventBridge API:

• Actions (p. 2): An alphabetical list of all EventBridge actions

• Data Types (p. 170): An alphabetical list of all EventBridge data types

• Common Parameters (p. 247): Parameters that all Query actions can use

• Common Errors (p. 249): Client and server errors that all actions can return

• Regions and Endpoints: Supported Regions and endpoints for all AWS products

Alternatively, you can use one of the AWS SDKs to access EventBridge using an API that is tailored to your programming language or platform.

Developers in the AWS developer community also provide their own libraries, which you can ﬁnd at the following AWS developer centers:

• Java Developer Center

• JavaScript Developer Center

• AWS Mobile Services

• PHP Developer Center

• Python Developer Center

• Ruby Developer Center

• Windows and .NET Developer Center

(14)

Actions

The following actions are supported:

• ActivateEventSource (p. 4)

• CancelReplay (p. 6)

• CreateApiDestination (p. 9)

• CreateArchive (p. 12)

• CreateConnection (p. 15)

• CreateEventBus (p. 19)

• CreatePartnerEventSource (p. 22)

• DeactivateEventSource (p. 25)

• DeauthorizeConnection (p. 27)

• DeleteApiDestination (p. 30)

• DeleteArchive (p. 32)

• DeleteConnection (p. 34)

• DeleteEventBus (p. 37)

• DeletePartnerEventSource (p. 39)

• DeleteRule (p. 41)

• DescribeApiDestination (p. 44)

• DescribeArchive (p. 47)

• DescribeConnection (p. 50)

• DescribeEventBus (p. 54)

• DescribeEventSource (p. 57)

• DescribePartnerEventSource (p. 60)

• DescribeReplay (p. 62)

• DescribeRule (p. 66)

• DisableRule (p. 70)

• EnableRule (p. 73)

• ListApiDestinations (p. 76)

• ListArchives (p. 79)

• ListConnections (p. 82)

• ListEventBuses (p. 85)

• ListEventSources (p. 87)

• ListPartnerEventSourceAccounts (p. 90)

• ListPartnerEventSources (p. 93)

• ListReplays (p. 96)

• ListRuleNamesByTarget (p. 99)

• ListRules (p. 102)

• ListTagsForResource (p. 106)

• ListTargetsByRule (p. 109)

• PutEvents (p. 114)

• PutPartnerEvents (p. 117)

• PutPermission (p. 119)

(15)

• PutRule (p. 123)

• PutTargets (p. 128)

• RemovePermission (p. 141)

• RemoveTargets (p. 143)

• StartReplay (p. 147)

• TagResource (p. 151)

• TestEventPattern (p. 154)

• UntagResource (p. 157)

• UpdateApiDestination (p. 160)

• UpdateArchive (p. 163)

• UpdateConnection (p. 166)

(16)

ActivateEventSource

Activates a partner event source that has been deactivated. Once activated, your matching event bus will start receiving events from the event source.

Request Syntax

{

"Name": "string"

}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 247).

The request accepts the following data in JSON format.

Name (p. 4)

The name of the partner event source to activate.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: aws\.partner(/[\.\-_A-Za-z0-9]+){2,}

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors (p. 249).

ConcurrentModiﬁcationException

There is concurrent modiﬁcation on a rule, target, archive, or replay.

HTTP Status Code: 400 InternalException

This exception occurs due to unexpected causes.

HTTP Status Code: 500 InvalidStateException

The speciﬁed state is not a valid state for an event source.

HTTP Status Code: 400

(17)

See Also

OperationDisabledException

The operation you are attempting is not available in this region.

HTTP Status Code: 400 ResourceNotFoundException

An entity that you speciﬁed does not exist.

CancelReplay

Cancels the speciﬁed replay.

Request Syntax

{ "ReplayName": "string"

}

Request Parameters

ReplayName (p. 6)

The name of the replay to cancel.

Type: String

Pattern: [\.\-_A-Za-z0-9]+

Required: Yes

Response Syntax

{

"ReplayArn": "string", "State": "string", "StateReason": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

ReplayArn (p. 6)

The ARN of the replay to cancel.

Type: String

Pattern: ^arn:aws([a-z]|\-)*:events:([a-z]|\d|\-)*:([0-9]{12})?:.+\/[\.\-_A- Za-z0-9]+$

(19)

Errors

State (p. 6)

The current state of the replay.

Type: String

The reason that the replay is in the current state.

Type: String

Length Constraints: Maximum length of 512.

Pattern: .*

Errors

HTTP Status Code: 400 IllegalStatusException

An error occurred because a replay can be canceled only when the state is Running or Starting.

CreateApiDestination

Creates an API destination, which is an HTTP invocation endpoint conﬁgured as a target for events.

Request Syntax

{

"ConnectionArn": "string", "Description": "string", "HttpMethod": "string",

"InvocationEndpoint": "string",

"InvocationRateLimitPerSecond": number, "Name": "string"

}

Request Parameters

ConnectionArn (p. 9)

The ARN of the connection to use for the API destination. The destination endpoint must support the authorization type speciﬁed for the connection.

Type: String

Pattern: ^arn:aws([a-z]|\-)*:events:([a-z]|\d|\-)*:([0-9]{12})?:connection\/

[\.\-_A-Za-z0-9]+\/[\-A-Za-z0-9]+$

Required: Yes Description (p. 9)

A description for the API destination to create.

Type: String

Pattern: .*

Required: No HttpMethod (p. 9)

The method to use for the request to the HTTP invocation endpoint.

Type: String

InvocationEndpoint (p. 9)

The URL to the HTTP invocation endpoint for the API destination.

(22)

Response Syntax

Type: String

Pattern: ^((%[0-9A-Fa-f]{2}|[-()_.!~*';/?:@\x26=+$,A-Za-z0-9])+)([).!';/?:,])?

$

Required: Yes

InvocationRateLimitPerSecond (p. 9)

The maximum number of requests per second to send to the HTTP invocation endpoint.

Type: Integer

Valid Range: Minimum value of 1.

Required: No Name (p. 9)

The name for the API destination to create.

Type: String

Required: Yes

Response Syntax

{

"ApiDestinationArn": "string", "ApiDestinationState": "string", "CreationTime": number,

"LastModifiedTime": number }

Response Elements

ApiDestinationArn (p. 10)

The ARN of the API destination that was created by the request.

Type: String

Pattern: ^arn:aws([a-z]|\-)*:events:([a-z]|\d|\-)*:([0-9]{12})?:api- destination\/[\.\-_A-Za-z0-9]+\/[\-A-Za-z0-9]+$

ApiDestinationState (p. 10)

The state of the API destination that was created by the request.

(23)

Errors

Type: String

Valid Values: ACTIVE | INACTIVE CreationTime (p. 10)

A time stamp indicating the time that the API destination was created.

Type: Timestamp LastModiﬁedTime (p. 10)

A time stamp indicating the time that the API destination was last modiﬁed.

Type: Timestamp

Errors

InternalException

HTTP Status Code: 500 LimitExceededException

The request failed because it attempted to create resource beyond the allowed service quota.

HTTP Status Code: 400 ResourceAlreadyExistsException

The resource you are trying to create already exists.

CreateArchive

Creates an archive of events with the specified settings. When you create an archive, incoming events might not immediately start being sent to the archive. Allow a short period of time for changes to take effect. If you do not specify a pattern to filter events sent to the archive, all events are sent to the archive except replayed events. Replayed events are not sent to an archive.

Request Syntax

{ "ArchiveName": "string", "Description": "string", "EventPattern": "string", "EventSourceArn": "string", "RetentionDays": number }

Request Parameters

ArchiveName (p. 12)

The name for the archive to create.

Type: String

Required: Yes Description (p. 12)

A description for the archive.

Type: String

Pattern: .*

Required: No EventPattern (p. 12)

An event pattern to use to ﬁlter events sent to the archive.

Type: String Required: No EventSourceArn (p. 12)

The ARN of the event bus that sends events to the archive.

(25)

Response Syntax

Type: String

Required: Yes RetentionDays (p. 12)

The number of days to retain events for. Default value is 0. If set to 0, events are retained indeﬁnitely

Type: Integer

Required: No

Response Syntax

{ "ArchiveArn": "string", "CreationTime": number, "State": "string", "StateReason": "string"

}

Response Elements

ArchiveArn (p. 13)

The ARN of the archive that was created.

Type: String

Pattern: ^arn:aws([a-z]|\-)*:events:([a-z]|\d|\-)*:([0-9]{12})?:.+\/.+$

CreationTime (p. 13)

The time at which the archive was created.

Type: Timestamp State (p. 13)

The state of the archive that was created.

Type: String

StateReason (p. 13)

The reason that the archive is in the state.

Type: String

(26)

Errors

Pattern: .*

Errors

HTTP Status Code: 500 InvalidEventPatternException

The event pattern is not valid.

CreateConnection

Creates a connection. A connection deﬁnes the authorization type and credentials to use for authorization with an API destination HTTP endpoint.

Request Syntax

{ "AuthorizationType": "string", "AuthParameters": {

"ApiKeyAuthParameters": { "ApiKeyName": "string", "ApiKeyValue": "string"

},

"BasicAuthParameters": { "Password": "string", "Username": "string"

},

"InvocationHttpParameters": { "BodyParameters": [ {

"IsValueSecret": boolean, "Key": "string",

"Value": "string"

} ],

"HeaderParameters": [ {

"Value": "string"

} ],

"QueryStringParameters": [ {

"Value": "string"

} ] },

"OAuthParameters": {

"AuthorizationEndpoint": "string", "ClientParameters": {

"ClientID": "string", "ClientSecret": "string"

},

"HttpMethod": "string", "OAuthHttpParameters": { "BodyParameters": [ {

"Value": "string"

} ],

"HeaderParameters": [ {

"Value": "string"

}

(28)

Request Parameters

],

"QueryStringParameters": [ {

"Value": "string"

} ] } } },

"Description": "string", "Name": "string"

}

Request Parameters

AuthorizationType (p. 15)

The type of authorization to use for the connection.

Type: String

Valid Values: BASIC | OAUTH_CLIENT_CREDENTIALS | API_KEY Required: Yes

AuthParameters (p. 15)

A CreateConnectionAuthRequestParameters object that contains the authorization parameters to use to authorize with the endpoint.

Type: CreateConnectionAuthRequestParameters (p. 194) object Required: Yes

Description (p. 15)

A description for the connection to create.

Type: String

Pattern: .*

The name for the connection to create.

Type: String

Required: Yes

(29)

Response Syntax

{

"ConnectionArn": "string", "ConnectionState": "string", "CreationTime": number, "LastModifiedTime": number }

Response Elements

The ARN of the connection that was created by the request.

Type: String

[\.\-_A-Za-z0-9]+\/[\-A-Za-z0-9]+$

ConnectionState (p. 17)

The state of the connection that was created by the request.

Type: String

A time stamp for the time that the connection was created.

A time stamp for the time that the connection was last updated.

Type: Timestamp

Errors

(30)

See Also

CreateEventBus

Creates a new event bus within your account. This can be a custom event bus which you can use to receive events from your custom applications and services, or it can be a partner event bus which can be matched to a partner event source.

Request Syntax

{ "EventSourceName": "string", "Name": "string",

"Tags": [ {

"Key": "string", "Value": "string"

} ]}

Request Parameters

EventSourceName (p. 19)

If you are creating a partner event bus, this speciﬁes the partner event source that the new event bus will be matched with.

Type: String

The name of the new event bus.

Event bus names cannot contain the / character. You can't use the name default for a custom event bus, as this name is already used for your account's default event bus.

If this is a partner event bus, the name must exactly match the name of the partner event source that this event bus is matched to.

Type: String

Pattern: [/\.\-_A-Za-z0-9]+

Required: Yes Tags (p. 19)

Tags to associate with the event bus.

(32)

Response Syntax

Type: Array of Tag (p. 236) objects Required: No

Response Syntax

{ "EventBusArn": "string"

}

Response Elements

EventBusArn (p. 20)

The ARN of the new event bus.

Type: String

Errors

HTTP Status Code: 500 InvalidStateException

HTTP Status Code: 400 OperationDisabledException

(33)

See Also

CreatePartnerEventSource

Called by an SaaS partner to create a partner event source. This operation is not used by AWS customers.

Each partner event source can be used by one AWS account to create a matching partner event bus in that AWS account. A SaaS partner must create one partner event source for each AWS account that wants to receive those event types.

A partner event source creates events based on resources within the SaaS partner's service or application.

An AWS account that creates a partner event bus that matches the partner event source can use that event bus to receive events from the partner, and then process them using AWS Events rules and targets.

Partner event source names follow this format:

partner_name/event_namespace/event_name

partner_name is determined during partner registration and identiﬁes the partner to AWS customers.

event_namespace is determined by the partner and is a way for the partner to categorize their events.

event_name is determined by the partner, and should uniquely identify an event-generating resource within the partner system. The combination of event_namespace and event_name should help AWS customers decide whether to create an event bus to receive these events.

Request Syntax

{ "Account": "string", "Name": "string"

}

Request Parameters

Account (p. 22)

The AWS account ID that is permitted to create a matching partner event bus for this partner event source.

Type: String

Length Constraints: Fixed length of 12.

Pattern: \d{12}

Required: Yes Name (p. 22)

The name of the partner event source. This name must be unique and must be in the format partner_name/event_namespace/event_name . The AWS account that wants to use this partner event source must create a partner event bus with a name that matches the name of the partner event source.

(35)

Response Syntax

Type: String

Required: Yes

Response Syntax

{ "EventSourceArn": "string"

}

Response Elements

EventSourceArn (p. 23)

The ARN of the partner event source.

Type: String

Errors

(36)

See Also

DeactivateEventSource

You can use this operation to temporarily stop receiving events from the speciﬁed partner event source.

The matching event bus is not deleted.

When you deactivate a partner event source, the source goes into PENDING state. If it remains in PENDING state for more than two weeks, it is deleted.

To activate a deactivated partner event source, use ActivateEventSource.

Request Syntax

{

"Name": "string"

}

Request Parameters

Name (p. 25)

The name of the partner event source to deactivate.

Type: String

Required: Yes

Response Elements

Errors

(38)

See Also

InvalidStateException

DeauthorizeConnection

Removes all authorization parameters from the connection. This lets you remove the secret from the connection so you can reuse it without having to create a new connection.

Request Syntax

{ "Name": "string"

}

Request Parameters

Name (p. 27)

The name of the connection to remove authorization from.

Type: String

Required: Yes

Response Syntax

{

"ConnectionArn": "string", "ConnectionState": "string", "CreationTime": number, "LastAuthorizedTime": number, "LastModifiedTime": number }

Response Elements

The ARN of the connection that authorization was removed from.

Type: String

(40)

Errors

[\.\-_A-Za-z0-9]+\/[\-A-Za-z0-9]+$

ConnectionState (p. 27) The state of the connection.

Type: String

Type: Timestamp LastAuthorizedTime (p. 27)

A time stamp for the time that the connection was last authorized.

A time stamp for the time that the connection was last updated.

Type: Timestamp

Errors

DeleteApiDestination

Deletes the speciﬁed API destination.

Request Syntax

{ "Name": "string"

}

Request Parameters

Name (p. 30)

The name of the destination to delete.

Type: String

Required: Yes

Response Elements

Errors

(43)

See Also

DeleteArchive

Deletes the speciﬁed archive.

Request Syntax

{ "ArchiveName": "string"

}

Request Parameters

ArchiveName (p. 32)

The name of the archive to delete.

Type: String

Required: Yes

Response Elements

Errors

(45)

See Also

DeleteConnection

Deletes a connection.

Request Syntax

{

"Name": "string"

}

Request Parameters

Name (p. 34)

The name of the connection to delete.

Type: String

Required: Yes

Response Syntax

{

"ConnectionArn": "string", "ConnectionState": "string", "CreationTime": number, "LastAuthorizedTime": number, "LastModifiedTime": number }

Response Elements

The ARN of the connection that was deleted.

Type: String

[\.\-_A-Za-z0-9]+\/[\-A-Za-z0-9]+$

(47)

Errors

ConnectionState (p. 34)

The state of the connection before it was deleted.

Type: String

Type: Timestamp LastAuthorizedTime (p. 34)

A time stamp for the time that the connection was last authorized before it wa deleted.

A time stamp for the time that the connection was last modiﬁed before it was deleted.

Type: Timestamp

Errors

DeleteEventBus

Deletes the speciﬁed custom event bus or partner event bus. All rules associated with this event bus need to be deleted. You can't delete your account's default event bus.

Request Syntax

{

"Name": "string"

}

Request Parameters

Name (p. 37)

The name of the event bus to delete.

Type: String

Pattern: [/\.\-_A-Za-z0-9]+

Required: Yes

Response Elements

Errors

DeletePartnerEventSource

This operation is used by SaaS partners to delete a partner event source. This operation is not used by AWS customers.

When you delete an event source, the status of the corresponding partner event bus in the AWS customer account becomes DELETED.

Request Syntax

{ "Account": "string", "Name": "string"

}

Request Parameters

Account (p. 39)

The AWS account ID of the AWS customer that the event source was created for.

Type: String

Length Constraints: Fixed length of 12.

Pattern: \d{12}

Required: Yes Name (p. 39)

The name of the event source to delete.

Type: String

Required: Yes

Response Elements

Errors

(52)

See Also

DeleteRule

Deletes the speciﬁed rule.

Before you can delete the rule, you must remove all targets, using RemoveTargets.

When you delete a rule, incoming events might continue to match to the deleted rule. Allow a short period of time for changes to take eﬀect.

If you call delete rule multiple times for the same rule, all calls will succeed. When you call delete rule for a non-existent custom eventbus, ResourceNotFoundException is returned.

Managed rules are rules created and managed by another AWS service on your behalf. These rules are created by those other AWS services to support functionality in those services. You can delete these rules using the Force option, but you should do so only if you are sure the other service is not still using that rule.

Request Syntax

{

"EventBusName": "string", "Force": boolean,

"Name": "string"

}

Request Parameters

EventBusName (p. 41)

The name or ARN of the event bus associated with the rule. If you omit this, the default event bus is used.

Type: String

Pattern: (arn:aws[\w-]*:events:[a-z]{2}-[a-z]+-[\w-]+:[0-9]{12}:event-bus\/)?

[/\.\-_A-Za-z0-9]+

Required: No Force (p. 41)

If this is a managed rule, created by an AWS service on your behalf, you must specify Force as True to delete the rule. This parameter is ignored for rules that are not managed rules. You can check whether a rule is a managed rule by using DescribeRule or ListRules and checking the ManagedBy ﬁeld of the response.

Type: Boolean Required: No Name (p. 41)

The name of the rule.

(54)

Response Elements

Type: String

Required: Yes

Response Elements

Errors

HTTP Status Code: 500 ManagedRuleException

This rule was created by an AWS service on behalf of your account. It is managed by that service.

If you see this error in response to DeleteRule or RemoveTargets, you can use the Force

parameter in those calls to delete the rule or remove targets from the rule. You cannot modify these managed rules by using DisableRule, EnableRule, PutTargets, PutRule, TagResource, or UntagResource.

Examples

Deletes a rule named "test"

The following is an example of a DeleteRule request.

Sample Request

POST / HTTP/1.1

Host: events.<region>.<domain>

x-amz-Date: <Date>

Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-

type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature>

User-Agent: <UserAgentString>

(55)

See Also

Content-Type: application/x-amz-json-1.1 Content-Length: <PayloadSizeBytes>

Connection: Keep-Alive

X-Amz-Target: AWSEvents.DeleteRule {

"Name": "test"

}

Sample Response

HTTP/1.1 200 OK

x-amzn-RequestId: <RequestId>

Content-Type: application/x-amz-json-1.1 Content-Length: <PayloadSizeBytes>

Date: <Date>

DescribeApiDestination

Retrieves details about an API destination.

Request Syntax

{

"Name": "string"

}

Request Parameters

Name (p. 44)

The name of the API destination to retrieve.

Type: String

Required: Yes

Response Syntax

{ "ApiDestinationArn": "string", "ApiDestinationState": "string", "ConnectionArn": "string", "CreationTime": number, "Description": "string", "HttpMethod": "string",

"InvocationEndpoint": "string",

"InvocationRateLimitPerSecond": number, "LastModifiedTime": number,

"Name": "string"

}

Response Elements

ApiDestinationArn (p. 44)

The ARN of the API destination retrieved.

Type: String

(57)

Response Elements

Pattern: ^arn:aws([a-z]|\-)*:events:([a-z]|\d|\-)*:([0-9]{12})?:api- destination\/[\.\-_A-Za-z0-9]+\/[\-A-Za-z0-9]+$

ApiDestinationState (p. 44)

The state of the API destination retrieved.

Type: String

Valid Values: ACTIVE | INACTIVE ConnectionArn (p. 44)

The ARN of the connection speciﬁed for the API destination retrieved.

Type: String

[\.\-_A-Za-z0-9]+\/[\-A-Za-z0-9]+$

A time stamp for the time that the API destination was created.

Type: Timestamp Description (p. 44)

The description for the API destination retrieved.

Type: String

Pattern: .*

HttpMethod (p. 44)

The method to use to connect to the HTTP endpoint.

Type: String

The URL to use to connect to the HTTP endpoint.

Type: String

Pattern: ^((%[0-9A-Fa-f]{2}|[-()_.!~*';/?:@\x26=+$,A-Za-z0-9])+)([).!';/?:,])?

$

InvocationRateLimitPerSecond (p. 44)

The maximum number of invocations per second to speciﬁed for the API destination. Note that if you set the invocation rate maximum to a value lower the rate necessary to send all events received on to the destination HTTP endpoint, some events may not be delivered within the 24-hour retry window. If you plan to set the rate lower than the rate necessary to deliver all events, consider using a dead-letter queue to catch events that are not delivered within 24 hours.

(58)

Errors

Type: Integer

LastModiﬁedTime (p. 44)

A time stamp for the time that the API destination was last modiﬁed.

Type: Timestamp Name (p. 44)

The name of the API destination retrieved.

Type: String

Amazon EventBridge

Amazon EventBridge

API Reference

API Version 2015-10-07

Amazon EventBridge: API Reference

Table of Contents

Amazon EventBridge API Reference

Actions

ActivateEventSource

Request Syntax

Request Parameters

Response Elements

Errors

See Also

CancelReplay

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateApiDestination

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateArchive

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateConnection

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateEventBus

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreatePartnerEventSource

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DeactivateEventSource

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DeauthorizeConnection

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DeleteApiDestination

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DeleteArchive

Request Syntax

Request Parameters

Response Elements

Errors