기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# Webhook를 통해 DevOps 에이전트 호출
<a name="configuring-capabilities-for-aws-devops-agent-invoking-devops-agent-through-webhook"></a>

Webhook를 사용하면 외부 시스템이 자동으로 AWS DevOps 에이전트 조사를 트리거할 수 있습니다. 이를 통해 티켓팅 시스템, 모니터링 도구 및 인시던트 발생 시 HTTP 요청을 보낼 수 있는 기타 플랫폼과 통합할 수 있습니다.

## 사전 조건
<a name="prerequisites"></a>

웹후크 액세스를 구성하기 전에 다음을 갖추어야 합니다.
+ in AWS DevOps 에이전트에 구성된 에이전트 공간
+  AWS DevOps 에이전트 콘솔에 대한 액세스
+ Webhook 요청을 보낼 외부 시스템

## Webhook 유형
<a name="webhook-types"></a>

AWS DevOps Agent는 다음과 같은 유형의 웹후크를 지원합니다.
+ **통합별 웹후크 -** Dynatrace, Splunk, Datadog, New Relic, ServiceNow 또는 Slack과 같은 타사 통합을 구성할 때 자동으로 생성됩니다. 이러한 웹후크는 특정 통합과 연결되며 통합 유형에 따라 결정되는 인증 방법을 사용합니다.
+ **일반 웹후크 **- 특정 통합에서 다루지 않는 소스에서 조사를 트리거하기 위해 수동으로 생성할 수 있습니다. 일반 웹후크는 현재 **HMAC** 인증을 사용합니다(베어러 토큰은 현재 사용할 수 없음).
+ **Grafana 알림 웹후크 **- Grafana는 웹후크 연락 지점을 통해 알림 알림을 AWS DevOps 에이전트에 직접 보낼 수 있습니다. 사용자 지정 알림 템플릿을 포함한 설정 지침은 [Grafana 연결을](connecting-telemetry-sources-connecting-grafana.md) 참조하세요.

## Webhook 인증 방법
<a name="webhook-authentication-methods"></a>

웹후크의 인증 방법은 연결된 통합에 따라 달라집니다.

**HMAC 인증** - 다음에서 사용:
+ Dynatrace 통합 웹후크
+ 일반 웹후크(특정 타사 통합에 연결되지 않음)

**베어러 토큰 인증** - 다음에서 사용:
+ Splunk 통합 웹후크
+ Datadog 통합 웹후크
+ New Relic 통합 웹후크
+ ServiceNow 통합 웹후크
+ Slack 통합 웹후크
+ Grafana 통합 웹후크

### HMAC 인증 이해
<a name="understanding-hmac-authentication"></a>

HMAC(해시 기반 메시지 인증 코드)는 웹후크 요청의 무결성과 신뢰성을 모두 확인하는 암호화 메커니즘입니다. HMAC 인증으로 웹후크를 전송할 때 SHA-256 알고리즘으로 보안 키를 사용하여 요청 타임스탬프와 페이로드를 함께 해싱하여 서명을 생성합니다. AWS DevOps 에이전트는 독립적으로 동일한 해시를 계산하고 두 서명을 비교합니다. 일치하는 경우 요청이 수락됩니다.

타임스탬프가 서명에 포함되므로 HMAC는 재생 방지 기능도 제공합니다. AWS DevOps Agent는 과거의 타임스탬프가 너무 먼 요청을 거부하여 공격자가 유효한 요청을 캡처하고 재전송하지 못하도록 할 수 있습니다.

### HMAC 토큰과 베어러 토큰 중에서 선택
<a name="choosing-between-hmac-and-bearer-token"></a>


| 고려 사항 | HMAC | 베어러 토큰 | 
| --- | --- | --- | 
| 설정 복잡성 | 더 복잡함 - 클라이언트는 타임스탬프와 페이로드를 사용하여 각 요청에 대한 서명을 계산해야 합니다. | 더 간단함 - Authorization 헤더에 정적 토큰 포함 | 
| 페이로드 무결성 | Verified - 서명 후 페이로드를 수정하면 서명이 무효화됩니다. | 확인되지 않음 - 토큰이 발신자를 인증하지만 페이로드 콘텐츠를 보호하지 않습니다. | 
| 재생 보호 | 내장 - 서명의 타임스탬프를 통해 서버가 기한 경과 요청을 거부할 수 있습니다. | 내장되지 않음 - 캡처된 토큰은 교체될 때까지 재사용할 수 있습니다. | 
| 비밀 노출 위험 | 하위 - 보안 암호가 요청에서 전송되지 않고 계산된 서명만 전송됩니다. | 높음 - 모든 요청 헤더에서 토큰이 전송되므로 트래픽이 가로채면 노출이 증가합니다. | 
| 사용해야 하는 경우 | 일반 웹후크 또는 엄격한 규정 준수 요구 사항이 있는 환경과 같이 더 강력한 보안 보장이 필요한 경우에 권장됩니다. | HTTPS를 통한 관리형 SaaS 통합과 같이 통합의 용이성이 우선순위이고 네트워크 전송이 신뢰할 수 있는 경우에 적합합니다. | 

**참고:** 인증 방법은 통합 유형에 따라 결정됩니다. 통합별 웹후크(Splunk, Datadog, New Relic, ServiceNow, Slack, Grafana)는 보유자 토큰 인증을 사용합니다. Dynatrace 및 일반 웹후크는 HMAC 인증을 사용합니다. 통합별 웹후크의 인증 방법은 변경할 수 없습니다.

## Webhook 액세스 구성
<a name="configuring-webhook-access"></a>

### 1단계: Webhook 구성으로 이동
<a name="step-1-navigate-to-the-webhook-configuration"></a>

1.  AWS Management Console에 로그인하고 AWS DevOps 에이전트 콘솔로 이동합니다.

1. 에이전트 스페이스 선택

1. **기능** 탭으로 이동

1. **Webhook** 섹션에서 **구성을** 클릭합니다.

### 2단계: Webhook 자격 증명 생성
<a name="step-2-generate-webhook-credentials"></a>

**통합별 웹후크의 경우:**

타사 통합 구성을 완료하면 Webhook가 자동으로 생성됩니다. Webhook 엔드포인트 URL 및 자격 증명은 통합 설정 프로세스가 끝날 때 제공됩니다.

**일반 웹후크의 경우:**

1. **웹후크 생성을 클릭합니다.**

1. 시스템에서 HMAC 키 페어를 생성합니다.

1. 생성된 키와 보안 암호를 안전하게 저장하므로 다시 검색할 수 없습니다.

1. 제공된 웹후크 엔드포인트 URL 복사

### 3단계: 외부 시스템 구성
<a name="step-3-configure-your-external-system"></a>

Webhook 엔드포인트 URL 및 자격 증명을 사용하여 요청을 AWS DevOps Agent로 보내도록 외부 시스템을 구성합니다. 특정 구성 단계는 외부 시스템에 따라 다릅니다.

## Webhook 자격 증명 관리
<a name="managing-webhook-credentials"></a>

**자격 증명 제거** - 웹후크 자격 증명을 삭제하려면 웹후크 구성 섹션으로 이동하여 **제거**를 클릭합니다. 자격 증명을 제거한 후에는 새 자격 증명을 생성할 때까지 웹후크 엔드포인트가 더 이상 요청을 수락하지 않습니다.

**자격 증명 재생성** - 새 자격 증명을 생성하려면 먼저 기존 자격 증명을 제거한 다음 새 키 페어 또는 토큰을 생성합니다.

## Webhook 사용
<a name="using-the-webhook"></a>

### Webhook 요청 형식
<a name="webhook-request-format"></a>

조사를 트리거하려면 외부 시스템이 HTTP POST 요청을 웹후크 엔드포인트 URL로 보내야 합니다.

**버전 1(HMAC 인증)의 경우:**

헤더:
+ `Content-Type: application/json`
+ `x-amzn-event-signature: <HMAC signature>`
+ `x-amzn-event-timestamp: <+%Y-%m-%dT%H:%M:%S.000Z>`

HMAC 서명은 SHA-256을 사용하여 보안 키로 요청 본문에 서명하여 생성됩니다.

**버전 2(베어러 토큰 인증)의 경우:**

헤더:
+ `Content-Type: application/json`
+ `Authorization: Bearer <your-token>`

**요청 본문:**

요청 본문에는 인시던트에 대한 정보가 포함되어야 합니다.

```
json

{
  "title": "Incident title",
  "severity": "high",
  "affectedResources": ["resource-id-1", "resource-id-2"],
  "timestamp": "2025-11-23T18:00:00Z",
  "description": "Detailed incident description",
  "data": {
    "metadata": {
        "region": "us-east-1",
        "environment": "production"
    }
  }
}
```

**페이로드 스키마:**

```
{
    eventType: 'incident';
    incidentId: string;
    action: 'created' | 'updated' | 'closed' | 'resolved';
    priority: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "MINIMAL";
    title: string;
    description?: string;
    timestamp?: string;
    service?: string;
    // The original event generated by service is attached here.
    data?: object;
}
```

### 예제 코드
<a name="example-code"></a>

**버전 1(HMAC 인증) - JavaScript:**

```
const crypto = require('crypto');

// Webhook configuration
const webhookUrl = 'https://your-webhook-endpoint.amazonaws.com/invoke';
const webhookSecret = 'your-webhook-secret-key';

// Incident data
const incidentData = {  
    eventType: 'incident',
    incidentId: 'incident-123',
    action: 'created',
    priority: "HIGH",
    title: 'High CPU usage on production server',
    description: 'High CPU usage on production server host ABC in AWS account 1234 region us-east-1',
    timestamp: new Date().toISOString(),
    service: 'MyTestService',
    data: {
      metadata: {
        region: 'us-east-1',
        environment: 'production'
      }
    }
};

// Convert data to JSON string
const payload = JSON.stringify(incidentData);
const timestamp = new Date().toISOString();
const hmac = crypto.createHmac("sha256", webhookSecret);
hmac.update(`${timestamp}:${payload}`, "utf8");
const signature = hmac.digest("base64");

// Send the request
fetch(webhookUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-amzn-event-timestamp': timestamp,
    'x-amzn-event-signature': signature
  },
  body: payload
})
.then(res => {
  console.log(`Status Code: ${res.status}`);
  return res.text();
})
.then(data => {
  console.log('Response:', data);
})
.catch(error => {
  console.error('Error:', error);
});
```

**버전 1(HMAC 인증) - cURL:**

```
#!/bin/bash

# Configuration
WEBHOOK_URL="https://event-ai.us-east-1.api.aws/webhook/generic/YOUR_WEBHOOK_ID"
SECRET="YOUR_WEBHOOK_SECRET"

# Create payload
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
INCIDENT_ID="test-alert-$(date +%s)"

PAYLOAD=$(cat <<EOF
{
"eventType": "incident",
"incidentId": "$INCIDENT_ID",
"action": "created",
"priority": "HIGH",
"title": "Test Alert",
"description": "Test alert description",
"service": "TestService",
"timestamp": "$TIMESTAMP"
}
EOF
)

# Generate HMAC signature
SIGNATURE=$(echo -n "${TIMESTAMP}:${PAYLOAD}" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)

# Send webhook
curl -X POST "$WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "x-amzn-event-timestamp: $TIMESTAMP" \
-H "x-amzn-event-signature: $SIGNATURE" \
-d "$PAYLOAD"
```

**버전 2(베어러 토큰 인증) - JavaScript:**

```
function sendEventToWebhook(webhookUrl, secret) {
  const timestamp = new Date().toISOString();
  
  const payload = {
    eventType: 'incident',
    incidentId: 'incident-123',
    action: 'created',
    priority: "HIGH",
    title: 'Test Alert',
    description: 'Test description',
    timestamp: timestamp,
    service: 'TestService',
    data: {}
  };

  fetch(webhookUrl, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-amzn-event-timestamp": timestamp,
      "Authorization": `Bearer ${secret}`,  // Fixed: template literal
    },
    body: JSON.stringify(payload),
  });
}
```

**버전 2(베어러 토큰 인증) - cURL:**

```
#!/bin/bash

# Configuration
WEBHOOK_URL="https://event-ai.us-east-1.api.aws/webhook/generic/YOUR_WEBHOOK_ID"
SECRET="YOUR_WEBHOOK_SECRET"

# Create payload
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
INCIDENT_ID="test-alert-$(date +%s)"

PAYLOAD=$(cat <<EOF
{
"eventType": "incident",
"incidentId": "$INCIDENT_ID",
"action": "created",
"priority": "HIGH",
"title": "Test Alert",
"description": "Test alert description",
"service": "TestService",
"timestamp": "$TIMESTAMP"
}
EOF
)

# Send webhook
curl -X POST "$WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "x-amzn-event-timestamp: $TIMESTAMP" \
-H "Authorization: Bearer $SECRET" \
-d "$PAYLOAD"
```

## 웹후크 문제 해결
<a name="troubleshooting-webhooks"></a>

### 200을 받지 못한 경우
<a name="if-you-do-not-receive-a-200"></a>

200과 Webhook와 같은 메시지가 수신되면 인증이 통과되었고 시스템에서 확인 및 처리할 수 있도록 메시지가 대기열에 있음을 나타냅니다. 200은 얻지 못하지만 4xx는 인증 또는 헤더에 문제가 있을 가능성이 높습니다. 인증을 디버깅하는 데 도움이 되도록 curl 옵션을 사용하여 수동으로 전송해 보세요.

### 200을 받지만 조사가 시작되지 않는 경우
<a name="if-you-receive-a-200-but-an-investigation-does-not-start"></a>

잘못된 페이로드가 원인일 수 있습니다.

1. 타임스탬프와 인시던트 ID가 모두 업데이트되고 고유한지 확인합니다. 중복 메시지는 중복 제거됩니다.

1. 메시지가 유효한 JSON인지 확인합니다.

1. 형식이 올바른지 확인합니다.

### 200을 수신하고 조사가 즉시 취소되는 경우
<a name="if-you-receive-a-200-and-investigation-is-immediately-cancelled"></a>

해당 월의 한도에 도달했을 가능성이 높습니다. 해당하는 경우 AWS 연락처에 문의하여 속도 제한 변경을 요청하십시오.

## 관련 주제
<a name="related-topics"></a>
+ [에이전트 스페이스 생성](getting-started-with-aws-devops-agent-creating-an-agent-space.md)
+ [DevOps 에이전트 웹 앱이란 무엇입니까?](about-aws-devops-agent-what-is-a-devops-agent-web-app.md)
+ [DevOps 에이전트 IAM 권한](aws-devops-agent-security-devops-agent-iam-permissions.md)