Webhook を使って DevOps Agent を CloudWatch アラーム駆動で起動してみた

はじめに

AWS DevOps Agent は、インシデント発生時に自動で調査、根本原因の特定、緩和策の提案まで行ってくれるサービスです。
しかし 2025 年 12 月現在、CloudWatch は DevOps Agent と直接連携することができないため、自動的に調査を走らせるためには Webhook を手動で作成する必要があります。
今回は、CloudWatch アラーム → Lambda → DevOps Agent Webhook という構成で、アラームの発火をトリガーに DevOps Agent の調査を自動的に走らせる方法について紹介します。

DevOps Agent とは

re:Invent 2025 にて「Frontier Agents」 と呼ばれる、AWS における自律型 AI エージェントの概念が発表されました。
DevOps Agent は Frontier Agents のうちの 1 つで、障害調査・原因特定・緩和策提案などを行ってくれるのが最大の特徴です。
他にも、トポロジーを確認できたり、DevOps Agent の調査結果をもとに直接 AWS サポートケースが作成できたりするなど、一連のインシデント対応に便利な機能が提供されています。

DevOps Agent における Webhook

Webhook を利用すると、外部システムのイベントをトリガーに AWS DevOps Agent の調査を自動的に開始できます。
DevOps Agent の Webhook には以下の 2 種類があります。

• Integration-specific webhooks
  • Dynatrace、Splunk、Datadog、New Relic、ServiceNow、Slack などのサードパーティ統合を設定すると自動的に生成される
• Generic webhooks
  • 上記以外のソースから調査をトリガーしたい場合に手動で作成する

CloudWatch はサードパーティ統合に含まれないため、Generic webhooks を使用する必要があります。

検証シナリオ

Webhook の設定に入る前に、監視対象のリソースを構築します。
ドキュメントにテストシナリオが用意されているので、今回はそちらを使用します。

以下の CloudFormation テンプレートを用いて、一連のリソースを構築します。

AWSTemplateFormatVersion: "2010-09-09"
Description: AWS DevOpsAgent Lambda Error Test Stack

Resources:
  LambdaExecutionRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: AWS-DevOpsAgentLambdaTestRole
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: lambda.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
      Tags:
        - Key: Name
          Value: AWS-DevOpsAgent-Lambda-Test-Role
        - Key: Purpose
          Value: AWS-DevOpsAgent-Testing

  TestLambdaFunction:
    Type: AWS::Lambda::Function
    Properties:
      FunctionName: AWS-DevOpsAgent-test-lambda
      Runtime: python3.12
      Handler: index.lambda_handler
      Role: !GetAtt LambdaExecutionRole.Arn
      Code:
        ZipFile: |
          import json
          import random
          from datetime import datetime

          def lambda_handler(event, context):
              print(f"AWS DevOpsAgent Test Lambda - {datetime.now()}")
              print(f"Event: {json.dumps(event)}")

              error_scenarios = [
                  "Simulated database connection timeout",
                  "Test API rate limit exceeded",
                  "Intentional validation error for AWS DevOpsAgent testing"
              ]

              error_message = random.choice(error_scenarios)
              print(f"Generating test error: {error_message}")

              raise Exception(f"AWS DevOpsAgent Test Error: {error_message}")
      Description: AWS DevOpsAgent beta test function - intentionally generates errors
      Timeout: 30
      Tags:
        - Key: Name
          Value: AWS-DevOpsAgent-Test-Lambda
        - Key: Purpose
          Value: AWS-DevOpsAgent-Testing

  LambdaErrorAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: AWS-DevOpsAgent-Lambda-Error-Test
      AlarmDescription: AWS-DevOpsAgent beta test - Lambda error rate alarm
      MetricName: Errors
      Namespace: AWS/Lambda
      Statistic: Sum
      Period: 60
      EvaluationPeriods: 1
      Threshold: 0
      ComparisonOperator: GreaterThanThreshold
      Dimensions:
        - Name: FunctionName
          Value: !Ref TestLambdaFunction
      TreatMissingData: notBreaching

Outputs:
  LambdaFunctionName:
    Description: Lambda Function Name for testing
    Value: !Ref TestLambdaFunction

  LambdaFunctionArn:
    Description: Lambda Function ARN
    Value: !GetAtt TestLambdaFunction.Arn

  AlarmName:
    Description: CloudWatch Alarm Name
    Value: !Ref LambdaErrorAlarm

  TestCommand:
    Description: AWS CLI command to test the function
    Value: !Sub aws lambda invoke --function-name ${TestLambdaFunction} --payload '{"test":"AWS DevOpsAgent validation"}' response.json

CloudWatch アラーム駆動を実現する手順

ここから具体的に、CloudWatch アラーム駆動で DevOps Agent の調査を自動で起動する設定方法について記載していきます。
① Webhook の作成
② Webhook 呼び出し用 Lambda の作成
③ CloudWatch アラームと Lambda の連携
の順に設定していきます。

① Webhook の作成

DevOps Agent の Agent Space を作成し、その詳細画面から「Capabilities > Webhook > Add」を押下します。

Step1

Webhook に送信するデータスキーマについての指定が記載されています。

Step2

Generic webhooks は HMAC 認証を使用しており、手順やサンプルコードが記載されています。

Step3

Webhook URL とシークレットキーが発行されます。
セキュアな場所に保管し、「Add」を押下します。

Webhook が作成されていることを確認します。

② Webhook 呼び出し用 Lambda の作成

関数の作成

Webhook を呼び出すための Lambda 関数を作成します。
Webhook 作成時の Step2 で TypeScript のサンプルコードが記載されていたため、今回は Node.js をランタイムに使用しました。
以下のコードを貼り付けてデプロイします。

import { createHmac } from "node:crypto";

export const handler = async (event) => {
  console.log("Received event:", JSON.stringify(event, null, 2));

  const webhookUrl = process.env.WEBHOOK_URL;
  const secret = process.env.WEBHOOK_SECRET;

  // CloudWatch Alarmから直接呼ばれた場合のペイロード取得
  const alarmData = event;

  const timestamp = new Date().toISOString();
  const incidentId = `cw-${alarmData.alarmData?.alarmName || 'unknown'}-${Date.now()}`;

  // DevOps Agent用ペイロード構築
  const payload = {
    eventType: "incident",
    incidentId: incidentId,
    action: "created",
    priority: "HIGH",
    title: `CloudWatch Alarm: ${alarmData.alarmData?.alarmName || 'Unknown'}`,
    description: alarmData.alarmData?.state?.reason || "CloudWatch Alarm triggered",
    timestamp: timestamp,
    service: alarmData.alarmData?.configuration?.metrics?.[0]?.metricStat?.metric?.namespace || "AWS",
    data: {
      alarmName: alarmData.alarmData?.alarmName,
      alarmArn: alarmData.alarmArn,
      state: alarmData.alarmData?.state,
      previousState: alarmData.alarmData?.previousState,
      configuration: alarmData.alarmData?.configuration
    }
  };

  // HMAC署名生成
  const hmac = createHmac("sha256", secret);
  hmac.update(`${timestamp}:${JSON.stringify(payload)}`, "utf8");
  const signature = hmac.digest("base64");

  // DevOps Agentへ送信
  const response = await fetch(webhookUrl, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-amzn-event-timestamp": timestamp,
      "x-amzn-event-signature": signature,
    },
    body: JSON.stringify(payload),
  });

  const responseText = await response.text();
  console.log(`Response status: ${response.status}, body: ${responseText}`);

  return {
    statusCode: response.status,
    body: responseText,
  };
};

上記の Lambda コードは、① Webhook の設定の Step1,2 の情報をもとに Claude Opus 4.5 により生成されたものです。

環境変数の設定

「設定 > 環境変数」から、取得した Webhook URL、シークレットキーを環境変数に設定します。

アクセス権限の設定

「設定 > アクセス権限 > リソースベースのポリシーステートメント」から、Lambda 側で CloudWatch アラームからの呼び出しを許可する必要があります。

③ CloudWatch アラームと Lambda の連携

CloudWatch アラームに Lambda アクションを設定

CloudFormation により作成された CloudWatch アラームAWS-DevOpsAgent-Lambda-Error-Testの詳細画面から「アクション > 編集」を押下し、Lambda アクションに ② で作成した Lambda を指定します。
これにより、アラームが発火したタイミングで Lambda を呼び出すことができます。

これで設定は完了です。

動作確認

CloudWatch アラーム駆動で DevOps Agent の調査が自動で開始するか確認します。
ドキュメントの手順に従い、Lambda 関数AWS-DevOpsAgent-test-lambdaでテストします。

テストを実行するとエラーが発生しました（想定通り）。

その後 CloudWatch アラームを見ると、アラーム状態であることが確認できました。

この状態で、DevOps Agent が自動で調査を開始していたら OK です。
DevOps Agent コンソール内の「Operator access」を押下し、専用の Web サイトに遷移すると、以下のように最新のイベントの Status が「In Progress」となっていました。OK です！

また肝心の DevOps Agent の調査内容についても、本シナリオにおいては正しく調査、原因特定ができていることがわかりました。

まとめ

CloudWatch アラーム → Lambda → DevOps Agent Webhook という構成で、アラームの発火をトリガーに DevOps Agent の調査を自動で起動する方法について紹介しました。
とはいえ、アラームごとに毎回この構成を組むのは大変なので、GA されるときには Lambda を経由せずとも自動で調査を走らせられることを期待しています。