EventBridgeV2 / Client / create_subscriber

create_subscriber¶

EventBridgeV2.Client.create_subscriber(**kwargs)¶

Creates a subscriber on an event bus, which delivers matching events to the configured target. The bus must be ACTIVE. Retries carrying the same ClientToken are idempotent.

Request Syntax

response = client.create_subscriber(
    Name='string',
    EventBusArn='string',
    InvokeConfiguration={
        'RoleArn': 'string',
        'LambdaParameters': {
            'InvocationType': 'EVENT'|'REQUEST_RESPONSE',
            'Qualifier': 'string',
            'DurableExecutionName': 'string',
            'TenantId': 'string',
            'InvocationTimeoutSeconds': 'string'
        },
        'SqsParameters': {
            'MessageGroupId': 'string',
            'MessageDeduplicationId': 'string',
            'DelaySeconds': 'string',
            'MessageAttributes': {
                'string': {
                    'DataType': 'string',
                    'StringValue': 'string',
                    'BinaryValue': 'string'
                }
            },
            'MessageSystemAttributes': {
                'string': {
                    'DataType': 'string',
                    'StringValue': 'string',
                    'BinaryValue': 'string'
                }
            }
        },
        'SnsParameters': {
            'MessageGroupId': 'string',
            'MessageDeduplicationId': 'string',
            'Subject': 'string',
            'MessageStructure': 'string',
            'MessageAttributes': {
                'string': {
                    'DataType': 'string',
                    'StringValue': 'string',
                    'BinaryValue': 'string'
                }
            }
        },
        'KinesisParameters': {
            'PartitionKey': 'string',
            'ExplicitHashKey': 'string'
        },
        'StepFunctionsParameters': {
            'InvocationType': 'EVENT'|'REQUEST_RESPONSE',
            'Name': 'string',
            'TraceHeader': 'string',
            'InvocationTimeoutSeconds': 'string'
        },
        'HttpParameters': {
            'PathParameterValues': [
                'string',
            ],
            'HeaderParameters': {
                'string': 'string'
            },
            'QueryStringParameters': {
                'string': 'string'
            },
            'InvocationTimeoutSeconds': 'string'
        },
        'UniversalTargetParameters': {
            'Input': 'string',
            'InvocationTimeoutSeconds': 'string'
        },
        'EventBusV2Parameters': {
            'Metadata': {
                'string': 'string'
            },
            'SystemMetadata': {
                'EventGroupId': 'string',
                'DeduplicationId': 'string'
            },
            'DeduplicationConfiguration': {
                'DeduplicationType': 'CONTENT_BASED'
            }
        },
        'TargetArn': 'string'
    },
    Description='string',
    FilterConfiguration={
        'Language': 'EVENT_BRIDGE_PATTERN',
        'Filters': [
            {
                'Pattern': 'string',
                'Scope': 'DATA'|'METADATA'|'SYSTEM_METADATA'
            },
        ]
    },
    Type='FIFO'|'UNORDERED',
    StartingPosition='LATEST'|'POINT_IN_TIME',
    PointInTimeConfiguration={
        'PointType': 'HORIZON'|'TIMESTAMP',
        'StartingPoint': datetime(2015, 1, 1),
        'EndPoint': datetime(2015, 1, 1)
    },
    BatchConfiguration={
        'MaxBatchSize': 123,
        'MaxBatchWindowInSeconds': 123
    },
    Transformer={
        'Type': 'RAW'|'WITH_METADATA'|'JSONATA',
        'JsonataConfiguration': {
            'Expression': 'string'
        }
    },
    RetryPolicy={
        'MaxRetryAttempts': 123,
        'MaxEventAgeInSeconds': 123,
        'RetryStrategy': 'ALL'
    },
    OnFailureConfiguration={
        'Arn': 'string'
    },
    LogConfiguration={
        'Level': 'OFF'|'ERROR'|'INFO',
        'IncludePayload': 'FULL'|'ON_ERROR_ONLY'
    },
    State='RUNNING'|'STOPPED',
    Tags={
        'string': 'string'
    },
    ClientToken='string'
)

Parameters:

Name (string) –
[REQUIRED]

Name of a subscriber. The first character must be alphanumeric; the remaining characters may also include ‘.’, ‘-’, and ‘_’.
EventBusArn (string) –
[REQUIRED]

The Amazon Resource Name (ARN) that uniquely identifies an event bus.
InvokeConfiguration (dict) –
[REQUIRED]

Configuration for how the subscriber invokes its target.
- RoleArn (string) – [REQUIRED]
  
  IAM role the service assumes to invoke the target. Must belong to the calling account.
- LambdaParameters (dict) –
  
  Lambda invocation parameters for subscribers. Values are forwarded to the Lambda Invoke API. Every string member accepts a literal or a JSONata expression (e.g. “{% $events.Data.qualifier %}”).
  - InvocationType (string) –
    
    Lambda invocation type. EVENT invokes the function asynchronously; REQUEST_RESPONSE waits for its result.
  - Qualifier (string) –
    
    Lambda qualifier: $LATEST, $LATEST.PUBLISHED, a numeric version, or an alias. Accepts a JSONata expression.
  - DurableExecutionName (string) –
    
    Durable execution name. Accepts a JSONata expression.
  - TenantId (string) –
    
    Tenant identifier. Accepts a JSONata expression.
  - InvocationTimeoutSeconds (string) –
    
    Timeout in seconds for each invocation of the target. String-typed so the value may be a JSONata expression.
- SqsParameters (dict) –
  
  SQS invocation parameters for subscribers. Values are forwarded to the SQS SendMessageBatch API. All scalar values accept a literal or a JSONata expression (e.g. “{% $events.Data.groupId %}”).
  - MessageGroupId (string) –
    
    Message group ID for FIFO queues. Accepts JSONata expression.
  - MessageDeduplicationId (string) –
    
    Message deduplication ID for FIFO queues. Accepts JSONata expression.
  - DelaySeconds (string) –
    
    Delay in seconds before the message becomes visible, standard queues only. Accepts JSONata expression.
  - MessageAttributes (dict) –
    
    Custom message attributes (name/type/value).
    - (string) –
      
      Message attribute name. The ceiling is wide enough to hold a JSONata expression, because a name may be a literal or an expression resolved once per delivered event.
      - (dict) –
        
        A custom SQS message attribute (data type plus string or binary value).
        
        DataType (string) –
        
        Attribute data type. Requiredness, the accepted vocabulary, and any custom label belong to SQS, which rejects an attribute without a data type on delivery.
        
        StringValue (string) –
        
        String attribute value. A JSONata expression resolves once per delivered event.
        
        BinaryValue (string) –
        
        Base64-encoded literal binary attribute value.
  - MessageSystemAttributes (dict) –
    
    System message attributes (e.g., AWSTraceHeader).
    - (string) –
      
      Message attribute name. The ceiling is wide enough to hold a JSONata expression, because a name may be a literal or an expression resolved once per delivered event.
      - (dict) –
        
        A custom SQS message attribute (data type plus string or binary value).
        
        DataType (string) –
        
        Attribute data type. Requiredness, the accepted vocabulary, and any custom label belong to SQS, which rejects an attribute without a data type on delivery.
        
        StringValue (string) –
        
        String attribute value. A JSONata expression resolves once per delivered event.
        
        BinaryValue (string) –
        
        Base64-encoded literal binary attribute value.
- SnsParameters (dict) –
  
  SNS invocation parameters for subscribers. Values are forwarded to the SNS PublishBatch API. All scalar values accept a literal or a JSONata expression (e.g. “{% $events.Data.groupId %}”).
  - MessageGroupId (string) –
    
    Message group ID for FIFO topics. Accepts JSONata expression.
  - MessageDeduplicationId (string) –
    
    Message deduplication ID for FIFO topics. Accepts JSONata expression.
  - Subject (string) –
    
    Subject line for email protocol subscriptions. Accepts JSONata expression.
  - MessageStructure (string) –
    
    Per-protocol message formatting mode, forwarded to SNS Publish unchanged. Accepts JSONata expression.
  - MessageAttributes (dict) –
    
    Custom message attributes for SNS filtering.
    - (string) –
      
      Message attribute name. The ceiling is wide enough to hold a JSONata expression, because a name may be a literal or an expression resolved once per delivered event.
      - (dict) –
        
        A custom SNS message attribute (data type plus string or binary value).
        
        DataType (string) –
        
        Attribute data type. Requiredness and the accepted vocabulary belong to SNS, which rejects an attribute without a data type on delivery.
        
        StringValue (string) –
        
        String attribute value. A JSONata expression resolves once per delivered event.
        
        BinaryValue (string) –
        
        Base64-encoded literal binary attribute value.
- KinesisParameters (dict) –
  
  Kinesis Data Streams invocation parameters for subscribers. Values are forwarded to the Kinesis PutRecords API. All scalar values accept a literal or a JSONata expression (e.g. “{% $events.Data.partitionKey %}”).
  - PartitionKey (string) –
    
    Required by PutRecords even when an explicit hash key is supplied. Accepts JSONata expression.
  - ExplicitHashKey (string) –
    
    Explicit hash key forwarded to PutRecords unchanged. Accepts JSONata expression.
- StepFunctionsParameters (dict) –
  
  Step Functions invocation parameters for subscribers. Values are forwarded to the Step Functions StartExecution or StartSyncExecution API. Every string member accepts a literal or a JSONata expression (e.g. “{% $events.Data.executionName %}”).
  - InvocationType (string) –
    
    Selects StartExecution (EVENT) or StartSyncExecution (REQUEST_RESPONSE) at delivery.
  - Name (string) –
    
    Name for the execution. Must be unique per account/region/state machine. Accepts JSONata expression.
  - TraceHeader (string) –
    
    X-Ray trace header for distributed tracing. Accepts JSONata expression.
  - InvocationTimeoutSeconds (string) –
    
    Timeout in seconds for each invocation of the target (1-30). String-typed (not integer) so the value may be a JSONata expression.
- HttpParameters (dict) –
  
  HTTP invocation parameters for subscribers (API Gateway / API Destination). Values are forwarded to the HTTP endpoint.
  - PathParameterValues (list) –
    
    Values substituted, in order, for the path-parameter placeholders in an HTTP target’s endpoint path.
    - (string) –
  - HeaderParameters (dict) –
    
    Map of HTTP header names to values, sent with the request to an HTTP target.
    - (string) –
      - (string) –
  - QueryStringParameters (dict) –
    
    Map of query-string parameter names to values, appended to the request to an HTTP target.
    - (string) –
      - (string) –
  - InvocationTimeoutSeconds (string) –
    
    Timeout in seconds for each invocation of the target (1-30). String-typed (not integer) so the value may be a JSONata expression.
- UniversalTargetParameters (dict) –
  
  Parameters for USI (Universal Service Integration) targets. Used when TargetArn is in the format arn:aws:events:::aws-sdk:{service}:{apiAction}
  - Input (string) – [REQUIRED]
    
    JSON string or JSONata expression that produces the API request. Supports {% … %} JSONata expressions for dynamic values from the event.
  - InvocationTimeoutSeconds (string) –
    
    Timeout in seconds for each invocation of the target (1-30, default 30). Accepts a literal integer or a {% … %} JSONata expression evaluated against the event at invocation time. A JSONata expression is syntax-checked at create time. Resolved values outside of the range [1, 30] will be constrained to the nearest bound at delivery time. Defaults to 30 seconds when unset.
- EventBusV2Parameters (dict) –
  
  Parameters for forwarding events to another EventBridge event bus.
  - Metadata (dict) –
    
    Customer-defined metadata forwarded with each event.
    - (string) –
      - (string) –
  - SystemMetadata (dict) –
    
    Customer-controllable system metadata attached to each forwarded event.
    - EventGroupId (string) –
      
      Event group ID for FIFO ordering on the downstream bus. Accepts a literal or a JSONata expression.
    - DeduplicationId (string) –
      
      Deduplication ID for FIFO deduplication on the downstream bus. Accepts a literal or a JSONata expression.
  - DeduplicationConfiguration (dict) –
    
    Deduplication settings applied to the forwarded events on the downstream bus.
    - DeduplicationType (string) – [REQUIRED]
      
      How duplicate events are detected: by a hash of the event content (CONTENT_BASED). To deduplicate by a caller-supplied token instead, omit DeduplicationConfiguration and set DeduplicationId on each entry.
- TargetArn (string) – [REQUIRED]
  
  ARN of the target a subscriber invokes. The resource grammar is service-neutral because target services use different separators and the USI form omits region and account.
Description (string) – Free-text description. Used by every resource type that has one: event buses, subscribers, and event sources.
FilterConfiguration (dict) –
Configuration for filtering events delivered to a subscriber. On CreateSubscriber, Filters is required and must contain at least one Filter with a non-empty Pattern. On UpdateSubscriber, an empty FilterConfiguration:{} clears the existing filter. Any non-empty shape (including {Language:X} without Filters) must contain a valid Filters list — same contract as CreateSubscriber. A non-empty Filters list overwrites; an omitted FilterConfiguration preserves existing state. All Filters are implicitly ANDed — an event must match every Filter to be delivered.
- Language (string) –
  
  Defaults to EVENT_BRIDGE_PATTERN when not specified.
- Filters (list) –
  
  List of filters. An event must match every filter to be delivered.
  - (dict) –
    
    A single filter entry within a FilterConfiguration.
    - Pattern (string) – [REQUIRED]
      
      An event pattern, as a JSON string, that selects which events match.
    - Scope (string) – [REQUIRED]
      
      Scope of a filter pattern within a FilterConfiguration.
Type (string) – Delivery ordering mode of a subscriber: FIFO delivers events in order within an event group; UNORDERED delivers without an ordering guarantee.
StartingPosition (string) – Starting position for a subscriber.
PointInTimeConfiguration (dict) –
Point-in-time configuration for a subscriber. Only applicable when StartingPosition is POINT_IN_TIME.
- PointType (string) – [REQUIRED]
  
  Whether to start from the horizon or a specific timestamp.
- StartingPoint (datetime) –
  
  Timestamp to start from. Required when PointType is TIMESTAMP.
- EndPoint (datetime) –
  
  Timestamp to stop at. Optional.
BatchConfiguration (dict) –
Batching configuration for a subscriber.
- MaxBatchSize (integer) –
  
  The maximum number of events to include in a single batch delivered to the target. The service delivers up to this many events per batch; fewer may be delivered when the batch window elapses or the target’s per-batch limit is smaller. This is a maximum, not a guaranteed count. Valid range is 1-500 (default: 10, or the target API’s per-batch maximum). The resolved value applied by the service is returned on read.
- MaxBatchWindowInSeconds (integer) –
  
  The maximum time in seconds to wait for a batch to fill before delivering it to the target. This is a maximum; a batch may be delivered sooner if it reaches MaxBatchSize or another delivery condition is met. Valid range is 0-300 (default: 0, meaning no wait). The resolved value applied by the service is always returned on read.
Transformer (dict) –
Not applicable to universal (aws-sdk) targets, whose input transformation is UniversalTargetParameters.Input; a Transformer on such a target is rejected.
- Type (string) –
  
  Transform type.
- JsonataConfiguration (dict) –
  
  JSONata expression configuration. Required when Type is JSONATA.
  - Expression (string) – [REQUIRED]
    
    JSONata expression to transform the event. Must be wrapped in {% %} delimiters.
RetryPolicy (dict) –
Retry policy for a subscriber.
- MaxRetryAttempts (integer) –
  
  Maximum number of retry attempts (0-185, default: 5).
- MaxEventAgeInSeconds (integer) –
  
  Maximum age of an event in seconds before it is discarded (60-86400, default: 300).
- RetryStrategy (string) –
  
  Strategy for determining which exceptions are retried. Default: ALL.
OnFailureConfiguration (dict) –
On-failure configuration: where a failed delivery is sent. Shared by the subscriber and the EventSource.
- Arn (string) –
  
  The ARN of the destination that receives events that could not be delivered. An Amazon SQS queue is the supported destination.
LogConfiguration (dict) –
Log configuration for a subscriber.
- Level (string) –
  
  Minimum log level. Records below this level are not emitted. Defaults to OFF.
- IncludePayload (string) –
  
  Whether the customer event payload is embedded in log records. Defaults to ON_ERROR_ONLY.
State (string) – Customer-controlled run state of a subscriber, set on create or update. Distinct from the bus lifecycle vocabulary, where ACTIVE means “provisioned and healthy”. Delivery requires State RUNNING on a subscriber that is not revoked.
Tags (dict) –
Tags attached to a resource, as key-value pairs.
- (string) –
  - (string) –
ClientToken (string) –
Unique, case-sensitive identifier that ensures the idempotency of the request. The SDK generates one automatically when the field is omitted.

This field is autopopulated if not provided.

Return type:

dict

Returns:

Response Syntax

{
    'SubscriberArn': 'string',
    'Name': 'string',
    'EventBusArn': 'string',
    'Type': 'FIFO'|'UNORDERED',
    'StartingPosition': 'LATEST'|'POINT_IN_TIME',
    'PointInTimeConfiguration': {
        'PointType': 'HORIZON'|'TIMESTAMP',
        'StartingPoint': datetime(2015, 1, 1),
        'EndPoint': datetime(2015, 1, 1)
    },
    'State': 'RUNNING'|'STOPPED',
    'CreationTime': datetime(2015, 1, 1)
}

Response Structure

(dict) –
- SubscriberArn (string) –
  
  The Amazon Resource Name (ARN) that uniquely identifies a subscriber.
- Name (string) –
  
  Name of a subscriber. The first character must be alphanumeric; the remaining characters may also include ‘.’, ‘-’, and ‘_’.
- EventBusArn (string) –
  
  The Amazon Resource Name (ARN) that uniquely identifies an event bus.
- Type (string) –
  
  Delivery ordering mode of a subscriber: FIFO delivers events in order within an event group; UNORDERED delivers without an ordering guarantee.
- StartingPosition (string) –
  
  Starting position for a subscriber.
- PointInTimeConfiguration (dict) –
  
  Point-in-time configuration for a subscriber. Only applicable when StartingPosition is POINT_IN_TIME.
  - PointType (string) –
    
    Whether to start from the horizon or a specific timestamp.
  - StartingPoint (datetime) –
    
    Timestamp to start from. Required when PointType is TIMESTAMP.
  - EndPoint (datetime) –
    
    Timestamp to stop at. Optional.
- State (string) –
  
  Customer-controlled run state of a subscriber, set on create or update. Distinct from the bus lifecycle vocabulary, where ACTIVE means “provisioned and healthy”. Delivery requires State RUNNING on a subscriber that is not revoked.
- CreationTime (datetime) –
  
  The time the subscriber was created.

Exceptions

EventBridgeV2.Client.exceptions.LimitExceededException
EventBridgeV2.Client.exceptions.AccessDeniedException
EventBridgeV2.Client.exceptions.IdempotentParameterMismatchException
EventBridgeV2.Client.exceptions.ResourceNotFoundException
EventBridgeV2.Client.exceptions.ThrottlingException
EventBridgeV2.Client.exceptions.InvalidInputException
EventBridgeV2.Client.exceptions.ResourceAlreadyExistsException
EventBridgeV2.Client.exceptions.InternalException
EventBridgeV2.Client.exceptions.ConcurrentModificationException
EventBridgeV2.Client.exceptions.InvalidStateException