Microsoft Graph 웹후크를 SharePoint 및 M365에서 안정적으로 구축하는 방법

By Mirko Peters · 2025-11-16

보안 검증, 자동 갱신, 안정적인 알림 전달로 SharePoint 및 M365용 Microsoft Graph 웹후크를 안정적으로 구축하세요.

Automatically translated with AI from the original post. Read the English original

SharePoint 및 M365용 Microsoft Graph 웹후크를 안정적으로 구축하는 일은 경험이 많은 개발자에게도 쉽지 않습니다. 엔드포인트가 검증 토큰을 그대로 반환하지 않거나 200 OK 상태로 응답하지 않으면 검증에 실패하는 문제가 발생할 수 있습니다. 흔한 문제로는 방화벽에 의해 차단된 엔드포인트, 네트워크 설정 오류, 미들웨어 간섭 등이 있습니다. 서비스가 검증 요청을 받지 못하거나 엔드포인트를 공용 네트워크에서 접근할 수 없는 경우에는 재시도 누락과 구독 만료가 자주 발생합니다. 이 글에서는 이러한 함정을 피하고, 실무에 바로 적용할 수 있는 체크리스트와 모범 사례를 바탕으로 안정적이고 안전한 알림 파이프라인을 구축하는 방법을 알아봅니다.

핵심 요약

• Microsoft Graph 웹후크는 Microsoft 365의 변경 사항에 대한 실시간 알림을 제공하므로 지속적인 폴링이 필요하지 않습니다.

• 웹후크 엔드포인트가 공용 네트워크에서 접근 가능하고 HTTPS를 사용하도록 하여 보안과 안정성을 확보하세요.

• 검증 요청에 신속하게 응답하고 검증 토큰을 그대로 반환하여 웹후크 구독을 성공적으로 활성화하세요.

• 알림 전달 실패에 대비해 견고한 재시도 및 백오프 전략을 구현하여 데이터 손실을 방지하세요.

• 구독 갱신을 자동화하고 웹후크 파이프라인을 모니터링하여 지속적이고 안정적인 알림을 보장하세요.

Microsoft Graph 웹후크 기본 개념

Microsoft Graph 웹후크란

웹후크는 원본 시스템에서 이벤트가 발생하면 트리거되어 대상 시스템으로 전송되는 HTTP 요청이며, 대개 데이터 페이로드를 포함합니다. 웹후크는 자동화된 방식으로 동작합니다. 즉, 원본 시스템에서 해당 이벤트가 발생하면 자동으로 전송됩니다.

Microsoft Graph 웹후크를 사용하면 Microsoft 365 환경의 변경 사항에 대한 실시간 알림을 받을 수 있습니다. 즉, Microsoft Graph에 업데이트 여부를 지속적으로 조회할 필요가 없습니다. 대신 중요한 일이 발생하는 즉시 애플리케이션이 알림을 받습니다. 이를 통해 Microsoft Graph에서 접근 가능한 데이터와 최신 상태를 유지하고 동기화할 수 있습니다. 또한 최신 변경 사항을 확인하기 위해 Microsoft Graph에 반복적으로 요청을 보내는 폴링 인프라가 필요 없어집니다.

다음과 같은 여러 유형의 이벤트에 대해 알림을 설정할 수 있습니다.

• 메시지

• 일정

• 연락처

• 사용자

• 그룹

• 대화

• OneDrive 파일

• 알림

예를 들어, 새 사용자가 조직에 합류하면 타사 근무 시간 추적 시스템에 계정을 자동으로 생성하고 싶을 수 있습니다. 또한 누군가 SharePoint 문서 라이브러리나 OneDrive 폴더에 새 파일을 추가할 때 경비 보고와 같은 콘텐츠 처리를 트리거할 수도 있습니다.

안정성이 중요한 이유

Microsoft Graph 웹후크는 SharePoint 및 Microsoft 365 통합이 빠르게 반응하고 최신 상태를 유지하도록 하는 데 핵심적인 역할을 합니다. 웹후크 파이프라인이 안정적으로 동작하면 애플리케이션은 변경 사항에 실시간으로 대응합니다. 사용자는 항상 최신 데이터를 확인할 수 있어 사용자 경험이 향상되고 오래된 정보로 인한 위험도 줄어듭니다.

하지만 안정성 문제는 심각한 결과를 초래할 수 있습니다.

• 웹후크 실패는 적절히 처리되지 않으면 애플리케이션 기능을 저해할 수 있습니다.

• 트래픽이 갑자기 급증하면 서버에 과부하가 걸려 다운타임이 발생하고 웹후크 요청이 유실될 수 있습니다.

• 재전송 메커니즘이 없는 상태에서 웹후크를 제대로 소비하지 못하면 데이터 손실과 불일치가 발생할 수 있습니다.

• 보안이 적용되지 않은 웹후크 URL은 악용될 수 있어, 공격자가 잘못된 데이터를 전송할 수 있습니다.

견고한 솔루션을 구축하려면 웹후크와 델타 쿼리를 결합하여 변경 사항을 효율적으로 추적해야 합니다. 또한 구독을 정기적으로 확인하고 갱신하는 프로세스를 마련해야 합니다. 자주 업데이트되는 리소스의 경우 요청을 일괄 처리하면 부하를 관리하는 데 도움이 됩니다.

웹후크 설정 및 검증

SharePoint와 M365용 Microsoft Graph 웹후크를 설정하려면 몇 가지 중요한 단계를 거쳐야 합니다. 웹후크를 등록하고, 유효성 검사 요청을 처리하며, 엔드포인트를 보호해야 합니다. 각 단계는 알림 파이프라인이 안정적이고 안전하게 작동하도록 보장하는 데 중요한 역할을 합니다.

Microsoft Graph 웹후크 등록

먼저 웹후크 구독을 만듭니다. 이 과정을 통해 애플리케이션이 Microsoft 365 리소스의 변경 사항에 대한 알림을 받을 수 있습니다. 다음 단계에 따라 웹후크를 등록하십시오.

1. HTTPS를 사용하는 공개적으로 액세스 가능한 엔드포인트를 만듭니다. 이 엔드포인트가 Microsoft Graph의 알림을 받습니다.

2. Microsoft Graph의 /subscriptions 엔드포인트로 POST 요청을 보냅니다.

3. 구독 요청에서 다음을 지정합니다.

   • changeType: 추적할 변경 유형입니다(예: "created", "updated", "deleted").

   • notificationUrl: 웹후크 엔드포인트의 URL입니다.

   • resource: 모니터링할 리소스입니다(예: "/users" 또는 "/drive/root").

   • expirationDateTime: 구독이 만료되어야 하는 날짜와 시간입니다.

   • clientState 같은 선택 속성을 사용하면 알림의 출처를 확인하는 데 도움이 됩니다.

구독 요청 예시:

POST https://graph.microsoft.com/v1.0/subscriptions
Authorization: bearer eyJ0eXAiOiJ[..]
Content-Type: application/json

{
  "changeType": "updated",
  "clientState": "SecretClientState",
  "notificationUrl": "https://yourdomain.com/api/notifications",
  "resource": "/users",
  "expirationDateTime": "2024-05-01T00:00:00.0000000+00:00"
}

엔드포인트는 공개적으로 액세스할 수 있어야 하며 HTTPS로 보호되어야 합니다. Microsoft Graph는 구독을 완료하기 전에 알림 URL을 검증합니다. 알림을 계속 받으려면 구독을 정기적으로 갱신해야 합니다. 알림을 놓치지 않으려면 엔드포인트가 적시에 일관된 HTTP 응답을 반환해야 합니다.

등록에 필요한 필드를 요약하면 다음과 같습니다:

유효성 검사 요청 처리

웹후크를 등록하면 Microsoft Graph가 엔드포인트로 유효성 검사 요청을 보냅니다. 구독 과정을 완료하려면 이 요청에 올바르게 응답해야 합니다. 엔드포인트가 validationToken 쿼리 매개 변수가 포함된 GET 요청을 받으면, 이 토큰을 일반 텍스트 형식으로 응답 본문에 그대로 반환하고 200 OK 상태를 반환해야 합니다.

• validationToken을 그대로 반환하지 않으면 유효성 검사 오류가 발생합니다. 이 경우 Microsoft Graph가 엔드포인트를 확인할 수 없으므로 알림을 받을 수 없습니다.

• 구독에서 온 요청인지 확인하려면 clientState 속성을 사용해야 합니다.

• validationToken은 10초 이내에 일반 텍스트 형식으로 응답 본문에 반드시 반환하십시오.

💡 팁: 유효성 검사 요청에 빠르고 정확하게 응답하면 웹후크 구독이 문제없이 활성화됩니다.

HTTPS 및 엔드포인트 보안

웹후크 엔드포인트를 보호하는 것은 필수입니다. Microsoft Graph 웹후크는 통신 중 민감한 데이터를 보호하기 위해 HTTPS 암호화가 필요합니다. 공유 비밀 키로 생성된 서명을 확인하여 수신 요청을 검증해야 합니다. 콜백 URL에는 추측하기 어렵도록 복잡하고 무작위로 생성된 경로를 사용하십시오.

• Microsoft Graph API 엔드포인트에 대해 IP 허용 목록을 추가하십시오.

• 요청 헤더에 인증 토큰을 포함하십시오.

• API 사용량을 모니터링하여 비정상적인 패턴이나 급증을 탐지하십시오.

• Microsoft Graph 및 Outlook API에 대한 액세스를 제한하십시오. 권한이 있는 담당자만 액세스할 수 있어야 하며, 다단계 인증(MFA)을 적용해야 합니다.

• 행동 분석과 머신 러닝을 활용해 위협을 식별하는 고급 엔드포인트 보안 솔루션을 배포하십시오.

• 취약점을 찾아 수정하기 위해 정기적으로 보안 감사를 수행하십시오.

각 웹훅 콜백은 들어오는 HTTPS 요청의 Authentication 헤더에 서명된 JSON Web Token(JWT)을 포함합니다. 토큰의 무결성을 확인하려면 표준 OpenID Connect JWT 검증 기법을 사용할 수 있습니다.

모든 웹훅 엔드포인트에는 반드시 HTTPS를 사용해야 합니다. 이 요구 사항은 데이터를 보호하고 Microsoft 보안 표준 준수를 보장합니다. 엔드포인트를 보호하면 무단 액세스와 공격을 방지하는 데 도움이 됩니다.

이러한 단계를 따르면 SharePoint와 M365용 Microsoft Graph Webhooks 파이프라인을 안정적이고 안전하게 구성할 수 있습니다. 또한 애플리케이션이 알림을 신속하고 안전하게 수신하도록 보장할 수 있습니다.

알림 처리 및 보안

웹훅 엔드포인트를 설정했다면 수신되는 알림을 안전하고 안정적으로 처리해야 합니다. 이 단계를 통해 애플리케이션이 유효한 요청만 수락하고, Microsoft Graph Webhooks의 중요한 업데이트를 놓치지 않도록 할 수 있습니다.

JWT 토큰 인증 및 검증

Microsoft Graph의 모든 알림에는 Authorization 헤더에 JSON Web Token(JWT)이 포함되어 있습니다. 페이로드를 처리하기 전에 반드시 이 토큰을 검증해야 합니다. 올바른 JWT 검증은 승인되지 않았거나 변조된 요청으로부터 시스템을 보호합니다.

JWT 토큰을 인증하고 검증하려면 다음 단계를 따르십시오.

1. 토큰이 만료되지 않았는지 확인하십시오. 토큰에는 만료 시간이 포함되어 있으며, 이 시간이 지난 토큰은 거부해야 합니다.

2. 토큰을 Microsoft identity platform이 발급했는지 확인하십시오. 토큰의 서명을 검증하여 변경되지 않았는지 확인하십시오.

3. 토큰의 "audience" 클레임이 애플리케이션의 ID와 일치하는지 확인하십시오. 이 단계를 통해 토큰이 해당 앱을 위한 것인지 확인할 수 있습니다.

4. azp(authorized party) 속성이 애플리케이션의 예상 값과 일치하는지 확인하십시오.

팁: JWT 검증에는 항상 신뢰할 수 있는 라이브러리를 사용하십시오. 이러한 라이브러리는 흔히 발생하는 실수를 피하고 애플리케이션을 안전하게 유지하는 데 도움이 됩니다.

JWT 토큰을 처리할 때 흔한 보안 취약점도 주의해야 합니다.

• JWT 서명을 검증하지 않으면 공격자가 탐지되지 않은 채 토큰 내용을 변경할 수 있습니다.

• JWT 처리에서 'none' 알고리즘을 사용하면 공격자가 서명 검사를 우회할 수 있습니다.

• 서명 비밀 값이 취약하면 공격자가 유효한 토큰을 위조하기 쉬워집니다.

• 공격자는 JOSE 헤더에 특정 매개변수를 삽입해 시스템이 JWT를 처리하는 방식을 조작할 수 있습니다.

이러한 단계와 예방 조치를 따르면 정당한 알림만 애플리케이션에 도달하도록 보장할 수 있습니다.

알림 페이로드 처리

알림을 인증한 후에는 페이로드를 안전하게 처리해야 합니다. 알림 페이로드에는 웹훅을 트리거한 이벤트에 대한 정보가 담겨 있습니다. 데이터 무결성을 유지하고 보안 문제를 예방하려면 다음을 수행해야 합니다.

• 페이로드에 필요한 모든 필드가 있는지 확인하십시오. 누락된 필드는 오류나 불완전한 처리를 일으킬 수 있습니다.

• 모든 텍스트 필드를 화면에 표시하거나 데이터베이스에 저장하기 전에 정화(sanitize)하십시오. 이 단계는 인젝션 공격과 데이터 손상을 방지합니다.

• 스키마 검증을 사용해 페이로드가 예상 구조와 일치하는지 확인하십시오. 스키마 검증은 예기치 않은 변경이나 잘못된 형식의 데이터를 찾아내는 데 도움이 됩니다.

• 가능한 API 버전 변경에 대비해 코드를 준비하십시오. 유연한 파싱을 사용하면 Microsoft가 페이로드 형식을 변경하더라도 애플리케이션이 계속 동작합니다.

참고: 페이로드를 검증하고 정화하면 잘못된 형식의 데이터와 보안 위협으로부터 시스템을 보호할 수 있습니다.

재시도 및 백오프 로직 구현

네트워크 문제나 일시적인 장애로 알림 전달이 실패할 수 있습니다. 데이터 손실을 방지하려면 견고한 재시도 및 백오프 전략이 필요합니다. Microsoft는 재시도를 관리하기 위해 지수 백오프와 구조화된 큐를 사용할 것을 권장합니다.

흔히 사용되는 재시도 및 백오프 메커니즘을 요약한 표는 다음과 같습니다.

적절한 재시도 및 백오프 로직을 구현하지 않으면 애플리케이션이 알림을 잃거나 데이터 불일치를 일으킬 위험이 있습니다. 요청 실패나 속도 제한으로 인해 중요한 업데이트를 받지 못할 수도 있습니다. 지수 백오프는 제한된 요청을 관리하는 데 도움이 되며, 시스템이나 Microsoft Graph 웹훅에 과부하를 줄 가능성을 낮춰 줍니다.

🛡️ 모범 사례: 재시도 횟수를 항상 추적하고, 여러 번 재시도한 후에도 실패한 메시지는 폐기 큐로 옮기십시오. 이 방식을 사용하면 데이터를 잃지 않고도 지속적인 문제를 조사하고 해결할 수 있습니다.

JWT 토큰을 인증하고, 페이로드를 검증하고, 안정적인 재시도 로직을 구현하면 안전하고 복원력 있는 알림 파이프라인을 구축할 수 있습니다. 이러한 단계를 거치면 Microsoft Graph 웹훅의 모든 알림을 안전하고 효율적으로 처리할 수 있습니다.

구독 및 변경 내용 추적 관리

구독 자동 갱신

알림을 놓치지 않으려면 웹훅 구독이 계속 활성 상태여야 합니다. Microsoft Graph 구독은 설정된 기간이 지나면 만료됩니다. 구독을 갱신하지 않으면 애플리케이션이 업데이트를 더 이상 받지 못합니다. 다음과 같은 여러 방법으로 갱신을 자동화할 수 있습니다:

• 각 구독의 만료 날짜를 업데이트하려면 HTTP PATCH 요청을 보내십시오.

• 이 PATCH 요청을 매일 실행되도록 예약하십시오. 이렇게 하면 구독이 최신 상태를 유지하고 예기치 않은 만료를 방지할 수 있습니다.

• 모든 구독의 만료 시점을 추적하십시오. 만료가 가까운 구독은 갱신하십시오.

• 구독이 만료되면 알림 흐름을 복구하기 위해 즉시 새 구독을 만드십시오.

팁: 갱신을 자동화하면 수작업을 줄이고 시스템이 Microsoft Graph와 계속 연결된 상태를 유지할 수 있습니다.

모니터링 및 알림

웹훅 파이프라인의 상태를 반드시 모니터링해야 합니다. 구독 갱신이 실패하거나 엔드포인트가 응답하지 않으면 알림을 받도록 경고를 설정하십시오. 로깅을 사용해 수신된 알림과 갱신 시도를 추적하십시오. 이렇게 하면 사용자에게 영향을 주기 전에 문제를 발견할 수 있습니다.

• 구독 상태와 만료 날짜를 모니터링하십시오.

• 갱신 실패나 누락된 알림에 대한 경고를 설정하십시오.

• 문제 해결을 위해 모든 웹훅 이벤트와 오류를 기록하십시오.

🛎️ 사전 모니터링은 문제를 신속하게 해결하고 통합 환경을 안정적으로 유지하는 데 도움이 됩니다.

델타 쿼리를 사용한 변경 내용 추적

델타 쿼리를 사용하면 변경 내용을 효율적으로 추적할 수 있습니다. SharePoint 및 M365 리소스에서 새로 추가되거나 업데이트된 데이터만 받을 수 있어 잦은 폴링의 필요성을 줄이고 제한 발생 위험도 낮출 수 있습니다.

• 델타 쿼리를 사용하면 매번 모든 데이터를 내려받지 않고도 애플리케이션이 변경 내용을 추적할 수 있습니다.

• SharePoint 및 M365와 함께 사용하기 좋으며, 변경이 있을 때만 알림을 보냅니다.

• 델타 쿼리를 사용하면 대역폭을 절약하고 성능을 개선할 수 있습니다.

다만 델타 쿼리에는 몇 가지 제한 사항이 있습니다:

참고: 이러한 제한 사항을 처리하고 변경 내용 추적이 정확하도록 델타 쿼리 구현을 항상 테스트하십시오.

갱신 자동화, 파이프라인 모니터링, 델타 쿼리 사용을 결합하면 SharePoint 및 M365를 위한 안정적이고 효율적인 웹훅 시스템을 구축할 수 있습니다.

다음 과정을 따르면 안정적인 Microsoft Graph 웹훅을 구축할 수 있습니다. 먼저 구독을 만들고 델타 쿼리를 사용하여 변경 사항을 추적하십시오. 갱신은 자동화하고 파이프라인에서 문제가 없는지 모니터링하십시오. 모든 단계에서 유효성 검사, 보안, 복원력을 우선시하십시오. 운영 환경 준비 상태를 확인하려면 이 체크리스트를 검토하십시오:

• 문서를 최신 상태로 유지하고 지원 팀에 정보를 계속 공유하십시오.

• 구독 상태를 정기적으로 점검하도록 일정을 설정하십시오.

• CI 파이프라인 보안 검사를 사용하고 감사 추적을 유지하십시오.

SharePoint 및 M365 통합이 안정적으로 유지되도록 이러한 모범 사례를 적용하십시오.

자주 묻는 질문

만료된 Microsoft Graph 웹훅 구독은 어떻게 갱신합니까?

Microsoft Graph /subscriptions/{id} 엔드포인트에 PATCH 요청을 보내십시오. expirationDateTime 필드를 업데이트합니다. 이 작업을 매일 실행하도록 일정을 설정하십시오. 그래야 구독이 계속 활성 상태를 유지하고 알림 누락을 방지할 수 있습니다.

웹훅 엔드포인트의 유효성 검사에 실패하면 어떻게 해야 합니까?

엔드포인트가 응답 본문에 validationToken을 일반 텍스트로 반환하는지 확인하십시오. 200 OK 상태로 응답하십시오. 엔드포인트가 공개적으로 접근 가능하고 HTTPS를 사용하는지도 확인하십시오.

웹훅 엔드포인트는 어떻게 보호합니까?

모든 엔드포인트에 HTTPS를 사용하십시오. 모든 요청에서 JWT 토큰을 검증하십시오. 인증과 IP 허용 목록으로 액세스를 제한하십시오. 비정상적인 활동을 모니터링하십시오. 보안 설정을 정기적으로 감사하십시오.

웹훅과 함께 델타 쿼리를 사용해야 하는 이유는 무엇입니까?

델타 쿼리를 사용하면 새로운 데이터나 변경된 데이터만 추적할 수 있습니다. 이를 통해 대역폭 사용량이 줄고 성능이 향상됩니다. 매번 전체 데이터를 다운로드하지 않아도 되므로 통합이 더 빠르고 효율적입니다.

실패한 웹훅 알림은 어떻게 처리하는 것이 가장 좋습니까?

지수 백오프를 적용한 재시도 로직을 구현하십시오. 헤더나 큐를 사용해 재시도 횟수를 추적하십시오. 여러 번 재시도한 후에도 실패한 메시지는 포기 큐로 이동하십시오. 데이터 손실을 방지하려면 이러한 실패 원인을 조사하십시오.