Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Updating, pausing, and resuming a subscriber

UpdateSubscriber changes a subscriber in place. A top-level member you omit keeps its stored value; a configuration object you supply replaces the stored object whole, so to change one filter, pass the complete FilterConfiguration with every filter you want to keep. To pause a subscriber, pass --state STOPPED; to resume, pass --state RUNNING with a --resume-position.

What you can change

The following request replaces the subscriber's whole InvokeConfiguration, so it names the role and every target parameter the subscriber must keep. TargetArn is not part of the update; a subscriber's target cannot change.

{
    "SubscriberArn": "arn:aws:events:us-east-1:111122223333:subscriber/large-orders/EXAMPLEabcdef1234567890",
    "InvokeConfiguration": {
        "RoleArn": "arn:aws:iam::111122223333:role/NewSubscriberTargetRole",
        "SqsParameters": {
            "MessageGroupId": "{% $events.Data.customerId %}"
        }
    }
}

The following table lists each member of the request and what supplying it does.

Name, EventBusArn, Type, StartingPosition, PointInTimeConfiguration, and TargetArn identify the subscriber or fix its starting point and cannot be changed; tags change through TagResource and UntagResource. The update response carries the subscriber's identity, state, starting position, and LastModifiedTime; read the configuration back with DescribeSubscriber.

An update never moves the subscriber's position on the bus: it does not rewind, skip, or replay. To re-deliver past events under a new configuration, create a new subscriber with a starting position instead; see Replaying retained events to a subscriber.

Troubleshooting: an update cleared settings you did not change

An update replaces each configuration object you supply as a whole; see What you can change.

Updating filters

To replace the filters, pass a FilterConfiguration whose Filters list holds every filter the subscriber should have; EventBridge combines filters for different scopes with AND. To remove every filter, pass FilterConfiguration as {}.

Filter changes are limited to 24 per subscriber in any rolling 24 hours. Only a change to the set of scopes and patterns counts; re-submitting an identical FilterConfiguration does not. The 25th change fails with FILTER_CHANGE_LIMIT_EXCEEDED. This limit is not a Service Quota and cannot be raised, so a design that rewrites filters continuously should instead publish the varying value into the event and filter on it once.

Which configuration an already matched event uses

EventBridge matches an event to a subscriber and delivers it at different times, and it records which version of the filters matched each event. An update that changes what the filters match creates a new filter version, and EventBridge stores the transformer and target parameters with it. An event matched before the change is delivered with the old transformer and target parameters; an event matched after it uses the new ones. The same holds after a subscriber stops and resumes.

So when a filter and a transformer or target parameter form one behavior, change them in the same request. The following request pairs a new DATA filter with the transformer written for it, so no event is delivered with a mismatched pair.

{
    "SubscriberArn": "arn:aws:events:us-east-1:111122223333:subscriber/large-orders/EXAMPLEabcdef1234567890",
    "FilterConfiguration": {
        "Filters": [
            { "Scope": "DATA", "Pattern": "{\"type\":[\"priority\"]}" }
        ]
    },
    "Transformer": {
        "Type": "JSONATA",
        "JsonataConfiguration": {
            "Expression": "{% {\"version\": 2, \"event\": $events.Data} %}"
        }
    }
}

An update that changes only the transformer or the target parameters creates no filter version. Once it propagates, the new configuration applies to events that are still waiting for delivery and to later retry attempts. The delivery role, retry policy, on-failure destination, batching, and logging configuration always take the latest propagated values, whatever version matched the event. Because EventBridge can evaluate the transformer and target parameters again for a retry, a time-dependent or nondeterministic JSONata function such as $now() can produce a different result on each attempt; do not assume a retried request carries identical bytes.

UpdateSubscriber stores the change before it returns, and the delivery components pick it up after a propagation delay, during which events can still use the previous configuration. DescribeSubscriber confirms what is stored, not that every component has switched. After an update, publish a test event and check the target payload before you rely on the new behavior.

Only one subscriber create or delete runs at a time on a bus, across every account that uses it; a concurrent call fails with ConcurrentModificationException. Retry it.

Pausing and resuming

A subscriber delivers only while its State is RUNNING. Set it to STOPPED to pause; events continue to accumulate on the bus, bounded by retention. When you set it back to RUNNING, ResumePosition decides what happens to the backlog.

aws eventsv2 update-subscriber \
    --subscriber-arn arn:aws:events:us-east-1:111122223333:subscriber/large-orders/EXAMPLEabcdef1234567890 \
    --state STOPPED

aws eventsv2 update-subscriber \
    --subscriber-arn arn:aws:events:us-east-1:111122223333:subscriber/large-orders/EXAMPLEabcdef1234567890 \
    --state RUNNING \
    --resume-position LAST_PROCESSED

ResumePosition is accepted only on the call that moves the state from STOPPED to RUNNING. On that call EventBridge first makes the subscriber's delivery endpoint discoverable again; if that step fails, the call returns InternalException, nothing is saved, and the subscriber stays STOPPED, so retry the request. A subscriber that the bus owner has revoked does not deliver in either state; see Revoking a subscriber or an event source.

Errors an update can return

EventBridge validates the updated configuration against the subscriber's stored target type, so an SqsParameters block on a subscriber whose target is a Lambda function is rejected.