웹후크 이벤트 전달

아티클
10/18/2023

웹후크는 Azure Event Grid에서 이벤트를 수신하는 여러 가지 방법 중 하나입니다. 새 이벤트가 준비되면 Event Grid 서비스는 요청 본문에 이벤트 정보가 포함된 HTTP 요청을 구성된 엔드포인트로 게시합니다.

웹후크를 지원하는 여러 다른 서비스와 마찬가지로, Event Grid를 사용하려면 해당 엔드포인트로 이벤트 제공을 시작하기 전에 웹후크 엔드포인트에 대한 소유권을 증명해야 합니다. 이 요구 사항으로 인해 악의적인 사용자가 엔드포인트에서 과도한 이벤트를 발생하는 일이 방지됩니다.

Event Grid 이벤트를 사용한 엔드포인트 유효성 검사

다음 세 가지 Azure 서비스를 사용하는 경우 Azure 인프라는 자동으로 이 유효성 검사를 처리합니다.

Event Grid 커넥터를 포함하는 Azure Logic Apps
웹후크를 통한 Azure Automation
Event Grid Trigger를 포함하는 Azure Functions

HTTP 트리거 기반 Azure 함수와 같은 엔드포인트의 다른 형식을 사용하는 경우, 엔드포인트 코드가 Event Grid를 통해 핸드셰이크 유효성 검사에 참여해야 합니다. Event Grid는 두 가지 방법의 구독 유효성 검사를 지원합니다.

동기 핸드셰이크: 이벤트 구독 생성 시 Event Grid는 엔드포인트에 구독 유효성 검사 이벤트를 전송합니다. 이 이벤트의 스키마는 다른 Event Grid 이벤트와 비슷합니다. 이 이벤트의 데이터 부분에는 validationCode 속성이 포함됩니다. 애플리케이션은 예상된 이벤트 구독에 대해 유효성 검사 요청이 수행된 것인지 확인하고 응답에 유효성 검사 코드를 동기식으로 반환합니다. 이 핸드셰이크 메커니즘은 모든 Event Grid 버전에서 지원됩니다.
비동기 핸드셰이크: 특정 경우에 응답으로 validationCode를 동기적으로 반환할 수 없습니다. 예를 들어, 타사 서비스를 사용하는 경우(예: Zapier 또는 IFTTT) 유효성 검사 코드를 통해 프로그래밍 방식으로 응답할 수 없습니다.

Event Grid는 수동 유효성 검사 핸드셰이크를 지원합니다. API 버전 2018-05-01-미리 보기 이상을 사용하는 SDK 또는 도구에서 이벤트 구독을 만드는 경우 Event Grid는 구독 유효성 검사 이벤트의 데이터 부분에 validationUrl 속성을 전송합니다. 핸드셰이크를 완료하려면 이벤트 데이터에서 해당 URL을 찾은 후 GET 요청을 전송합니다. REST 클라이언트 또는 웹 브라우저를 사용할 수 있습니다.

제공된 URL은 5분 동안 유효합니다. 이 시간 동안 이벤트 구독의 프로비전 상태가 AwaitingManualAction입니다. 5분 안에 수동 유효성 검사를 완료하지 않은 경우 프로비저닝 상태가 Failed로 설정됩니다. 수동 유효성 검사를 시작하기 전에 이벤트 구독을 다시 작성해야 합니다.

이 인증 메커니즘에서는 수동 유효성 감시 모드로 들어가기 전에 유효성 검사 이벤트의 POST가 수락되었는지 알 수 있도록 웹후크 엔드포인트가 HTTP 상태 코드 200을 반환하도록 요구합니다. 즉, 엔드포인트가 200을 반환하지만 동기식으로 유효성 검사 응답을 반환하지 않는 경우 모드가 수동 유효성 검사 모드로 전환됩니다. 5분 안에 유효성 검사 URL에 대한 GET이 수신되는 경우, 유효성 검사 핸드셰이크가 성공했다고 간주됩니다.

참고

유효성 검사에 자체 서명된 인증서를 사용하는 것은 지원되지 않습니다. 대신 상용 CA(인증 기관)의 서명된 인증서를 사용하세요.

유효성 검사 세부 정보

이벤트 구독 생성/업데이트 시 Event Grid는 대상 엔드포인트에 구독 유효성 검사 이벤트를 게시합니다.
이벤트에는 헤더 값 aeg-event-type: SubscriptionValidation이 포함됩니다.
이벤트 본문에는 다른 Event Grid 이벤트와 동일한 스키마가 있습니다.
이벤트의 eventType 속성은 Microsoft.EventGrid.SubscriptionValidationEvent입니다.
이벤트의 data 속성에는 임의로 생성된 문자열을 포함한 validationCode 속성이 있습니다. 예: validationCode: acb13….
이벤트 데이터는 구독에 대해 수동으로 유효성 검사를 수행하기 위해 URL에 validationUrl 속성도 포함되어 있습니다.
배열에는 유효성 검사 이벤트만 포함됩니다. 다른 이벤트는 유효성 검사 코드를 에코 백한 후 별도의 요청으로 전송됩니다.
EventGrid 데이터 평면 SDK에는 구독 유효성 검사 이벤트 데이터 및 구독 유효성 검사 응답에 해당하는 클래스가 있습니다.

SubscriptionValidationEvent 예가 다음 예제에 나와 있습니다.

[
  {
    "id": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
    "topic": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "subject": "",
    "data": {
      "validationCode": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6",
      "validationUrl": "https://rp-eastus2.eventgrid.azure.net:553/eventsubscriptions/myeventsub/validate?id=0000000000-0000-0000-0000-00000000000000&t=2022-10-28T04:23:35.1981776Z&apiVersion=2018-05-01-preview&token=1A1A1A1A"
    },
    "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
    "eventTime": "2022-10-28T04:23:35.1981776Z",
    "metadataVersion": "1",
    "dataVersion": "1"
  }
]

엔드포인트 소유권을 증명하기 위해 다음 예제와 같이 validationResponse 속성의 유효성 검사 코드를 다시 에코합니다.

{
  "validationResponse": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6"
}

그리고 다음 단계 중 하나를 따릅니다.

HTTP 200 OK 응답 상태 코드를 반환해야 합니다. HTTP 202 Accepted는 유효한 Event Grid 구독 유효성 검사 응답으로 인식되지 않습니다. HTTP 요청은 30초 이내에 완료되어야 합니다. 작업이 30초 이내에 완료되지 않으면 작업이 취소되며, 5초 뒤에 다시 시도될 수 있습니다. 모든 시도가 실패하면 유효성 검사 핸드셰이크 오류로 간주됩니다.

애플리케이션이 유효성 검사 코드를 처리하고 반환할 준비가 되었다는 사실은 이벤트 구독을 만들었고 이벤트를 수신할 것으로 예상했음을 나타냅니다. 핸드셰이크 유효성 검사가 지원되지 않고 해커가 애플리케이션 URL을 알게 되는 시나리오를 상상해 보세요. 해커는 애플리케이션의 URL로 항목 및 이벤트 구독을 만들고 많은 이벤트를 전송하여 애플리케이션에 DoS 공격을 시작할 수 있습니다. 핸드셰이크 유효성 검사는 이를 방지합니다.

자체 이벤트 구독을 만들었기 때문에 이미 앱에 유효성 검사가 구현되어 있다고 상상해 보세요. 해커가 앱 URL을 사용하여 이벤트 구독을 만들더라도 올바르게 구현된 유효성 검사 요청 이벤트는 요청의 aeg-subscription-name 헤더를 검사하여 사용자가 인식하는 이벤트 구독인지 확인합니다.

올바른 핸드셰이크 구현 후에도 해커는 Event Grid에서 오는 것처럼 보이는 요청을 복제하여 앱(이미 이벤트 구독의 유효성을 검사했음)을 침범할 수 있습니다. 이를 방지하려면 Microsoft Entra 인증으로 웹후크를 보호해야 합니다. 자세한 내용은 Microsoft Entra로 보호된 엔드포인트에 이벤트 배달을 참조하세요.
또는 유효성 검사 URL에 GET 요청을 수동으로 전송하여 구독이 유효한지 수동으로 검사할 수 있습니다. 이벤트 구독은 유효성을 검사할 때까지 보류 상태로 유지됩니다. 유효성 검사 URL은 포트 553을 사용합니다. 방화벽 규칙이 포트 553을 차단하는 경우 성공적인 수동 핸드셰이크를 위한 업데이트 규칙이 필요합니다.

구독 유효성 검사 이벤트에 대한 유효성 검사에서 이벤트가 예상되는 이벤트 구독이 아님을 확인하면 200개의 응답을 반환하지 않거나 전혀 응답하지 않습니다. 따라서 유효성 검사가 실패합니다.

구독 유효성 검사 핸드셰이크 처리 예제를 보려면 C# 샘플을 참조하세요.

CloudEvents v1.0을 사용한 엔드포인트 유효성 검사

CloudEvents v1.0은 HTTP OPTIONS 메서드를 사용하여 자체 악용 방지 의미 체계를 구현합니다. 해당 서비스에 대한 자세한 내용은 여기에서 확인할 수 있습니다. 출력에 CloudEvents 스키마를 사용하는 경우, Event Grid는 Event Grid 유효성 검사 이벤트 메커니즘 대신 CloudEvents v1.0 악용 방지를 사용합니다.

이벤트 스키마 호환성

토픽을 만들 때 들어오는 이벤트 스키마가 정의됩니다. 또한 구독을 만들 때 나가는 이벤트 스키마가 정의됩니다. 다음 표에서는 구독을 만들 때 허용되는 호환성을 보여 줍니다.

들어오는 이벤트 스키마	나가는 이벤트 스키마	지원됨
Event Grid 스키마	Event Grid 스키마	예
	클라우드 이벤트 v1.0 스키마	예
	사용자 지정 입력 스키마	아니요
클라우드 이벤트 v1.0 스키마	Event Grid 스키마	아니요
	클라우드 이벤트 v1.0 스키마	예
	사용자 지정 입력 스키마	아니요
사용자 지정 입력 스키마	Event Grid 스키마	예
	클라우드 이벤트 v1.0 스키마	예
	사용자 지정 입력 스키마	예

다음 단계

이벤트 구독 유효성 검사 문제 해결 방법은 이벤트 구독 유효성 검사 문제 해결 문서를 참조하세요.