• Documentation
  • Pricing
© 2026 Serverless, Inc. All rights reserved.

Framework

  • Overview
  • Documentation
  • Plugins360
  • Pricing

Learn

  • Blog
  • GuidesUpdated
  • Examples240
  • Courses

Resources

  • Support
  • Security
  • Trust Center
  • Status

Community

  • Slack
  • GitHub47k
  • Forum
  • Meetups

Company

  • About
  • Careers
  • Contact
  • Partners

Legal

  • Terms of Service
  • Privacy Policy
  • Trademark
  • DMCA
Serverless Framework Logo

Serverless Framework

Intro
SetupUpgrading To V4ConceptsTutorialAWS CredentialsLicense Keys
DeployingPackagingBuildingTestingDev ModeServicesFunctions
OverviewHTTP (API Gateway v2)REST (API Gateway v1)ActiveMQApplication Load BalancerAlexa SkillAlexa Smart HomeCloudWatch EventCloudWatch LogCloudFrontCognito User PoolEventBridge EventIoTIoT Fleet ProvisioningKafkaKinesis & DynamoDBMSKRabbitMQS3ScheduleSNSSQSWebsocket
LayersManaged InstancesWeb Apps (Lambda Web Functions)Sandboxes (Lambda MicroVMs)MCP ServersAlertsVersion PruningDomainsIAM Function PermissionsParameters
OverviewSelf-reference serverless.ymlServerless CoreEnvironment VariablesCLI OptionsExternal YAML/JSON FilesJavascript propertiesGitDoppler
OverviewS3 ObjectsSSM Parameter Store & Secrets ManagerCloudFormation Stack Outputs
OverviewVaultTerraform State Output
ResourcesComposing ServicesDeployment BucketStateAgent SkillsPython support
OverviewRuntimeGatewayMemoryBrowserCode InterpreterDev Mode
API Gateway Proxy
OverviewGeneral ConfigurationAuthenticationAPI KeysData SourcesResolversPipeline FunctionsSubstitutionsCachingDelta SyncCustom DomainWAFCLI Commands
Deploying SAM/CFN TemplatesWorkflow Tips
OverviewCreating PluginsCLI OutputCustom CommandsCustom VariablesExtending the Configuration schemaExtending and overriding configuration
OverviewDashboardAxiom
Overviewagent docsagent inspectagent setupagent skills installagent skills list / readdeploydeploy functiondeploy listdevdiffinfoinvokeinvoke localloginlogin awslogin aws ssologsmetricspackageplugin installplugin uninstallprintprunereconcileremoverollbackrollback functionusage
OverviewConcepts
OverviewMetricsTracesTroubleshoot
OverviewNode.jsPython
OutputsProviders
OverviewBranch DeploymentsPreview DeploymentsCustom ScriptsTestingPrivate PackagesNotificationsMono ReposDeploy in your own CI/CDBest PracticesTroubleshootingFAQ
OverviewSetupToolsAWS Integration
Serverless.yml Reference
Examples and TutorialsConfiguration Validation
  1. Usage
  2. Events
  3. Cloud Watch Event

CloudWatch Events Rules

The cloudwatchEvent event triggers a Lambda function when an event on the default event bus matches a pattern, such as an EC2 instance changing state. CloudWatch Events is the earlier name of Amazon EventBridge: the Framework creates an EventBridge rule on the default event bus with the cloudwatchEvent event's pattern, the function as its target, and a permission for EventBridge to invoke the function. For custom event buses, schedules, retry policies and dead-letter queues, use the eventBridge event instead.

This serverless.yml runs a function whenever an EC2 instance enters the pending state:

# serverless.yml
service: my-service

provider:
  name: aws
  runtime: nodejs24.x

functions:
  instanceStateChange:
    handler: handler.instanceStateChange
    events:
      - cloudwatchEvent:
          event:
            source:
              - aws.ec2
            detail-type:
              - EC2 Instance State-change Notification
            detail:
              state:
                - pending

The handler receives the matching event, with the service-specific data in event.detail:

// handler.mjs
export const instanceStateChange = async (event) => {
  console.log(
    event['detail-type'],
    event.detail['instance-id'],
    event.detail.state,
  )
}

cloudwatchEvent event options

The cloudwatchEvent event accepts these keys:

KeyTypeDefaultDescription
eventobjectRequiredThe event pattern the rule matches
enabledbooleantrueWhether the rule is enabled
namestring, 1–64 charactersGenerated by CloudFormationThe rule name
descriptionstring, up to 512 charactersNo descriptionThe rule description
inputobject, or JSON string up to 8,192 charactersNot set: the function receives the eventA fixed payload passed instead of the event
inputPathJSONPath string, 1–256 charactersNot setThe part of the event passed to the function
inputTransformerobject with inputTemplate and inputPathsMapNot setA payload built from values in the event

Event patterns

The cloudwatchEvent event's event key is an EventBridge event pattern, written in YAML. The rule matches an event when every field in the pattern matches; a list matches any of its values. The pattern in the preceding example matches EC2 state-change events with the state pending.

Patterns also accept content filters, such as prefix, anything-but and numeric. This pattern matches every EC2 state change except to running:

functions:
  instanceStateChange:
    handler: handler.instanceStateChange
    events:
      - cloudwatchEvent:
          event:
            source:
              - aws.ec2
            detail-type:
              - EC2 Instance State-change Notification
            detail:
              state:
                - anything-but: running

For the pattern syntax, see Amazon EventBridge event patterns. For the events each AWS service sends, see Events from AWS services.

Input, input path and input transformer

By default, the function receives the whole event. To pass something else, set one of input, inputPath or inputTransformer on the cloudwatchEvent event; set at most one of them per event.

input passes a fixed payload instead of the event. An object is converted to JSON:

functions:
  instanceStateChange:
    handler: handler.instanceStateChange
    events:
      - cloudwatchEvent:
          event:
            source:
              - aws.ec2
          input:
            stage: dev
            action: audit

inputPath passes the part of the event that a JSONPath selects:

functions:
  instanceStateChange:
    handler: handler.instanceStateChange
    events:
      - cloudwatchEvent:
          event:
            source:
              - aws.ec2
          inputPath: '$.detail'

inputTransformer builds a payload from values in the event. inputPathsMap names the values with JSONPath, and inputTemplate (required) uses them as <name> placeholders:

functions:
  instanceStateChange:
    handler: handler.instanceStateChange
    events:
      - cloudwatchEvent:
          event:
            source:
              - aws.ec2
          inputTransformer:
            inputPathsMap:
              instance: '$.detail.instance-id'
              eventTime: '$.time'
            inputTemplate: '{"instance": "<instance>", "time": "<eventTime>"}'

Put a placeholder in quotes when its value is a string, so the result is valid JSON. For the template rules, see Amazon EventBridge input transformation.

Rule name and description

The cloudwatchEvent event's name and description set the rule's name and description:

functions:
  instanceStateChange:
    handler: handler.instanceStateChange
    events:
      - cloudwatchEvent:
          name: ec2-pending-instances
          description: Runs when an EC2 instance enters the pending state
          event:
            source:
              - aws.ec2
            detail-type:
              - EC2 Instance State-change Notification
            detail:
              state:
                - pending
  • name: 1 to 64 characters, using only ASCII letters, digits, ., - and _. It must be unique among the rules on the default event bus in the Region, so a fixed name stops you from deploying the same service to two stages in one Region; include the stage, as in ec2-pending-${sls:stage}. Without name, CloudFormation generates a unique name.
  • description: up to 512 characters.

See PutRule for the rule name rules.

Disable a rule

A cloudwatchEvent rule is enabled by default. To deploy the rule without triggering the function, set enabled: false:

functions:
  instanceStateChange:
    handler: handler.instanceStateChange
    events:
      - cloudwatchEvent:
          enabled: false
          event:
            source:
              - aws.ec2

Permissions for CloudWatch Events rules

For each cloudwatchEvent event, the Framework adds a lambda:InvokeFunction permission for events.amazonaws.com, limited to the rule's ARN. The function's execution role needs no extra permissions to receive events.

Troubleshooting CloudWatch Events rules

You can only set one of input, inputPath, or inputTransformer properties at the same time for cloudwatch events. ...

This happens when one cloudwatchEvent event sets more than one of input, inputPath and inputTransformer. Keep one of them; to send the same events with different payloads, add a second cloudwatchEvent event with the same event pattern.

Related

  • EventBridge events, for custom event buses, schedules, retry policies and dead-letter queues
  • CloudWatch settings in the serverless.yml reference
  • Amazon EventBridge rules
Edit this page
Prev Alexa Smart HomeNextCloudWatch Log

Contents

  • CloudWatch Events Rules
  • cloudwatchEvent event options
  • Event patterns
  • Input, input path and input transformer
  • Rule name and description
  • Disable a rule
  • Permissions for CloudWatch Events rules
  • Troubleshooting CloudWatch Events rules
  • You can only set one of input, inputPath, or inputTransformer properties at the same time for cloudwatch events. ...
  • Related

Related

GuidesPluginsExamplesSlack CommunitySupport