View invocation summaries for AWS CloudFormation Hooks - AWS CloudFormation

View invocation summaries for AWS CloudFormation Hooks

This topic describes how to view invocation summaries for AWS CloudFormation Hooks. Viewing invocation summaries can help you understand how Hooks are evaluating your resources and troubleshoot any issues that may arise during stack operations.

Invocations are specific instances when your validation logic (whether it's a AWS CloudFormation Guard rule, Lambda function, or Control Catalog proactive control) runs during a resource's lifecycle.

View invocation summaries in the console

You can view invocation information in the console in two ways: through the Invocation summary page for all invocations across your account, or through individual stack events for stack-specific invocations.

View all invocation summaries

The Invocation summary page provides a comprehensive view of all Hook invocations across all stacks in your account and Region for the past 90 days.

To view invocation summaries
  1. Sign in to the AWS Management Console and open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.

  2. On the navigation bar at the top of the screen, choose the AWS Region where you want to view Hook invocations.

  3. From the navigation pane, choose Invocation summary.

  4. The page displays a list of all Hook invocations from the past 90 days, including:

    • Invocation ID

    • Hook

    • Target

    • Mode (Warn or Fail)

    • Result (Warning, Pass, Failed, In progress)

    • Invocation time

    • Result message

  5. You can filter the list using the search bar at the top of the table to find specific invocations.

View stack-specific invocation information

You can also view invocation information for a specific stack through the stack events page.

To view Hook invocations for a specific stack
  1. Sign in to the AWS Management Console and open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.

  2. On the navigation bar at the top of the screen, choose the AWS Region where the stack operation occurred.

  3. From the navigation pane, choose Stacks.

  4. Select the stack you want to view Hook invocations for.

  5. Choose the Stack events tab.

  6. In the events list, look for events with Hook invocations complete in the Status reason column. For additional Hook invocation details, review the Hook invocations column.

View invocation summaries using the AWS CLI

Use the list-hook-results command to retrieve information about Hook invocations. This command supports the following filtering options:

  • Get all Hook invocation results (no parameters required)

  • Filter by Hook ARN (use --type-arn)

  • Filter by Hook ARN and status (use --type-arn and --status)

  • Search for specific targets (use --target-type and --target-id)

Filter results by Hook ARN

The following command lists all Hook invocation results for a specific Hook.

aws cloudformation list-hook-results \ --type-arn arn:aws:cloudformation:us-west-2:123456789012:type/hook/MyOrg-Security-ComplianceHook \ --region us-west-2

Example output:

{ "HookResults": [ { "TypeArn": "arn:aws:cloudformation:us-west-2:123456789012:type/hook/MyOrg-Security-ComplianceHook", "HookResultId": "59ef501c-0ac4-47c0-a193-e071cabf748d", "TypeName": "MyOrg::Security::ComplianceHook", "TypeVersionId": "00000001", "HookExecutionTarget": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack/39f29d10-73ed-11f0-abc1-0affdfe4aebb", "InvokedAt": "2025-08-08T00:18:39.651Z", "FailureMode": "WARN", "HookStatusReason": "...", "InvocationPoint": "PRE_PROVISION", "Status": "HOOK_COMPLETE_FAILED" }, ... ] }

For a description of the fields in the response, see HookResultSummary in the AWS CloudFormation API Reference.

Filter results by Hook ARN and status

To filter for a common status among the results, specify the --status option in the command. Valid values are:

  • HOOK_IN_PROGRESS: The Hook is currently running.

  • HOOK_COMPLETE_SUCCEEDED: The Hook completed successfully.

  • HOOK_COMPLETE_FAILED: The Hook completed but failed validation.

  • HOOK_FAILED: The Hook encountered an error during execution.

aws cloudformation list-hook-results \ --type-arn arn:aws:cloudformation:us-west-2:123456789012:type/hook/MyOrg-Security-ComplianceHook \ --status HOOK_COMPLETE_FAILED \ --region us-west-2

Example output:

{ "HookResults": [ { "TypeArn": "arn:aws:cloudformation:us-west-2:123456789012:type/hook/MyOrg-Security-ComplianceHook", "HookResultId": "59ef501c-0ac4-47c0-a193-e071cabf748d", "TypeName": "MyOrg::Security::ComplianceHook", "TypeVersionId": "00000001", "HookExecutionTarget": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack/39f29d10-73ed-11f0-abc1-0affdfe4aebb", "InvokedAt": "2025-08-08T00:18:39.651Z", "FailureMode": "WARN", "HookStatusReason": "...", "InvocationPoint": "PRE_PROVISION", "Status": "HOOK_COMPLETE_FAILED" }, ... ] }

For a description of the fields in the response, see HookResultSummary in the AWS CloudFormation API Reference.

Filter results by target type and target ID

The following command lists all Hook invocation results for a specific Cloud Control API request.

aws cloudformation list-hook-results \ --target-type CLOUD_CONTROL \ --target-id d417b05b-9eff-46ef-b164-08c76aec1801 \ --region us-west-2

Example output:

{ "HookResults": [ { "TargetType": "CLOUD_CONTROL", "TargetId": "d417b05b-9eff-46ef-b164-08c76aec1801", "HookResults": [ { "TypeArn": "arn:aws:cloudformation:us-west-2:123456789012:type/hook/MyOrg-Security-ComplianceHook", "HookResultId": "4e7f4766-d8fe-44e5-8587-5b327a148abe", "TypeName": "MyOrg::Security::ComplianceHook", "TypeVersionId": "00000001", "FailureMode": "WARN", "HookStatusReason": "...", "InvocationPoint": "PRE_PROVISION", "Status": "HOOK_COMPLETE_FAILED" }, ... ] } ] }

For a description of the fields in the response, see HookResultSummary in the AWS CloudFormation API Reference.