AWS::CloudFormation::LambdaHook - AWS CloudFormation
SyntaxPropertiesReturn valuesExamples

AWS::CloudFormation::LambdaHook

The AWS::CloudFormation::LambdaHook resource creates and activates a Lambda Hook. You can use a Lambda Hook to evaluate your resources before allowing stack operations. This resource forwards requests for resource evaluation to a Lambda function.

For more information, see Lambda Hooks in the AWS CloudFormation Hooks User Guide.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
  "Type" : "AWS::CloudFormation::LambdaHook",
  "Properties" : {
      "Alias" : String,
      "ExecutionRole" : String,
      "FailureMode" : String,
      "HookStatus" : String,
      "LambdaFunction" : String,
      "StackFilters" : StackFilters,
      "TargetFilters" : TargetFilters,
      "TargetOperations" : [ String, ... ]
    }
}

YAML

Type: AWS::CloudFormation::LambdaHook
Properties:
  Alias: String
  ExecutionRole: String
  FailureMode: String
  HookStatus: String
  LambdaFunction: String
  StackFilters: 
    StackFilters
  TargetFilters: 
    TargetFilters
  TargetOperations: 
    - String

Properties

Alias

The type name alias for the Hook. This alias must be unique per account and Region.

The alias must be in the form Name1::Name2::Name3 and must not begin with AWS. For example, Private::Lambda::MyTestHook.

Required: Yes

Type: String

Pattern: ^(?!(?i)aws)[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}$

Update requires: Replacement

ExecutionRole

The IAM role that the Hook assumes to invoke your Lambda function.

Required: Yes

Type: String

Pattern: arn:.+:iam::[0-9]{12}:role/.+

Maximum: 256

Update requires: No interruption

FailureMode

Specifies how the Hook responds when the Lambda function invoked by the Hook returns a FAILED response.

  • FAIL: Prevents the action from proceeding. This is helpful for enforcing strict compliance or security policies.

  • WARN: Issues warnings to users but allows actions to continue. This is useful for non-critical validations or informational checks.

Required: Yes

Type: String

Allowed values: FAIL | WARN

Update requires: No interruption

HookStatus

Specifies if the Hook is ENABLED or DISABLED.

Required: Yes

Type: String

Allowed values: ENABLED | DISABLED

Update requires: No interruption

LambdaFunction

Specifies the Lambda function for the Hook. You can use:

  • The full Amazon Resource Name (ARN) without a suffix.

  • A qualified ARN with a version or alias suffix.

Required: Yes

Type: String

Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?(-iso([a-z])?)?-[a-z]+-\d{1}:)?(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?

Minimum: 1

Maximum: 170

Update requires: No interruption

StackFilters

Specifies the stack level filters for the Hook.

Required: No

Type: StackFilters

Update requires: No interruption

TargetFilters

Specifies the target filters for the Hook.

Required: No

Type: TargetFilters

Update requires: No interruption

TargetOperations

Specifies which type of operation the Hook is run against.

Valid values: STACK | RESOURCE | CHANGE_SET | CLOUD_CONTROL

Required: Yes

Type: Array of String

Update requires: No interruption

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the Hook Amazon Resource Name (ARN). For example: arn:aws:cloudformation:us-west-2:123456789012:type/hook/MyLambdaHook.

For more information about using the Ref function, see Ref.

Fn::GetAtt

The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.

HookArn

Returns the ARN of a Lambda Hook.

Examples

Creating a Lambda Hook in a template

The following example demonstrates how to create a Lambda Hook in a template.

JSON

{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Description": "Create a Lambda Hook",
    "Parameters": {
        "HookFunctionArn": {
            "Description": "Hook Lambda Function ARN",
            "Type": "String"
        },
        "HookName": {
            "Description": "The name of your Hook",
            "Type": "String",
            "Default": "Test::Lambda::Hook",
            "AllowedPattern": "^(?!(?i)aws)[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}$"
        }
    },
    "Resources": {
        "LambdaInvokerHookRole": {
            "Type": "AWS::IAM::Role",
            "Properties": {
                "AssumeRolePolicyDocument": {
                    "Version": "2012-10-17",
                    "Statement": [
                        {
                            "Effect": "Allow",
                            "Principal": {
                                "Service": ["hooks.cloudformation.amazonaws.com"]
                            },
                            "Action": "sts:AssumeRole"
                        }
                    ]
                },
                "Path": "/",
                "Policies": [
                    {
                        "PolicyName": "LambdaInvokerHookPolicy",
                        "PolicyDocument": {
                            "Version": "2012-10-17",
                            "Statement": [
                                {
                                    "Effect": "Allow",
                                    "Action": ["lambda:InvokeFunction"],
                                    "Resource": {"Ref" : "HookFunctionArn"}
                                }
                            ]
                        }
                    }
                ]
            }
        },
        "MyLambdaHook": {
            "Type": "AWS::CloudFormation::LambdaHook",
            "Properties": {
                "LambdaFunction": {"Ref" : "HookFunctionArn"},
                "HookStatus": "ENABLED",
                "TargetOperations": [
                    "RESOURCE",
                    "STACK"
                ],
                "FailureMode": "WARN",
                "Alias": {"Ref" : "HookName"},
                "ExecutionRole": {
                    "Fn::GetAtt": [
                        "LambdaInvokerHookRole",
                        "Arn"
                    ]
                },
                "StackFilters": {
                    "FilteringCriteria": "ALL",
                    "StackNames": {
                        "Exclude": [{"Ref" : "AWS::StackName"}]
                    }
                }
            }
        }
    }
}

YAML

AWSTemplateFormatVersion: 2010-09-09
Description: Create a Lambda Hook
Parameters:
  HookFunctionArn:
    Description: Hook Lambda Function ARN
    Type: String
  HookName:
    Description: The name of your Hook
    Type: String
    Default: 'Test::Lambda::Hook'
    AllowedPattern: '^(?!(?i)aws)[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}$'
Resources:
  LambdaInvokerHookRole:
    Type: 'AWS::IAM::Role'
    Properties:
      AssumeRolePolicyDocument:
        Version: 2012-10-17
        Statement:
          - Effect: Allow
            Principal:
              Service:
                - hooks.cloudformation.amazonaws.com
            Action: 'sts:AssumeRole'
      Path: /
      Policies:
        - PolicyName: LambdaInvokerHookPolicy
          PolicyDocument:
            Version: 2012-10-17
            Statement:
              - Effect: Allow
                Action:
                  - 'lambda:InvokeFunction'
                Resource: !Ref HookFunctionArn
  MyLambdaHook:
    Type: 'AWS::CloudFormation::LambdaHook'
    Properties:
      LambdaFunction: !Ref HookFunctionArn
      HookStatus: ENABLED
      TargetOperations:
        - RESOURCE
        - STACK
      FailureMode: WARN
      Alias: !Ref HookName
      ExecutionRole: !GetAtt LambdaInvokerHookRole.Arn
      StackFilters:
        FilteringCriteria: ALL
        StackNames:
          Exclude:
            - !Ref AWS::StackName