Webhook 구성

Logto 콘솔에서 Webhook을 구성하여 애플리케이션에 실시간 이벤트 알림을 받고 원활하게 통합할 수 있습니다. 손쉬운 설정, 향상된 보안, 편리한 상태 모니터링 옵션을 제공합니다.

Webhook 생성하기

먼저, Logto Agent가 호출할 Webhook 엔드포인트를 생성하세요. 이 엔드포인트는 서버에 구현되어 HTTP 요청을 수신할 수 있어야 합니다.

Logto 콘솔에서 새로운 Webhook을 생성하려면 다음 단계를 따르세요:

Webhook 생성: 콘솔 > Webhooks로 이동하여 "Webhook 생성" 버튼을 클릭하세요.
이름: Webhook의 이름을 입력하세요. 이는 사용 시나리오를 정의하기 위한 참고용입니다.
엔드포인트 URL: 이벤트 발생 시 Webhook POST 요청을 받을 서버의 Endpoint URL을 입력하세요. 보안상의 이유로, 이 URL은 HTTPS를 통해 공개적으로 접근 가능해야 하며, 로컬 호스트 URL이어서는 안 됩니다.

노트:
서버는 Logto Webhook 요청을 수신한 즉시 HTTP 200("OK") 응답을 반환하여 요청이 정상적으로 수신되었음을 알려야 합니다.
해당 Webhook 이벤트의 로직 처리가 완료될 때까지 응답을 지연하면 Webhook이 타임아웃될 수 있습니다.
Logto Webhook에 200 이외의 응답을 반환하지 마세요. 이벤트 처리 중 오류가 발생하면 자체 서버에서 처리하세요.
이벤트: 나타나는 모달에서 이 Webhook을 트리거할 이벤트를 선택하세요. 서버의 과부하를 방지하기 위해 필요한 소수의 이벤트만 선택하는 것이 좋습니다. Webhook 생성 후 언제든지 선택한 이벤트를 변경할 수 있습니다.
비활성화 / 재활성화: 기본적으로 Webhook은 생성 직후 즉시 활성화됩니다. 일시적으로 Webhook을 중단하고 싶다면, 생성 후 헤더 우측 상단의 "점 세 개" 메뉴에서 비활성화하거나 다시 활성화할 수 있습니다.

서버가 Webhook 요청을 받을 준비가 되었다면, 요청을 안전하게 처리할 수 있는지 확인하는 것이 좋습니다. Logto는 각 Webhook 요청 페이로드에 대한 서명을 생성하여, 해당 요청이 Logto에서 온 것임을 검증할 수 있도록 합니다.

새로운 Webhook을 생성한 후, 보안을 강화할 수 있는 옵션이 제공됩니다:

서명 키: Logto는 각 Webhook마다 고유한 해시 서명(서명 키)을 생성합니다. 이 키를 엔드포인트 구현에서 요청 헤더로 포함할 수 있습니다. 서명 키를 검증하면 Webhook 페이로드가 Logto에서 왔으며, 무단 소스에 의해 변조되지 않았음을 확인할 수 있습니다. 자세한 코드는 Webhook 보안 강화하기를 참고하세요.
커스텀 헤더: Webhook 페이로드에 커스텀 헤더를 추가하여 추가적인 컨텍스트나 메타데이터를 제공할 수 있습니다. 이 기능을 통해 Webhook 데이터를 효과적으로 처리하는 데 도움이 되는 관련 정보를 추가할 수 있습니다.

서명 키를 활용하고 커스텀 헤더 추가를 고려함으로써 Webhook의 보안을 강화하고, 수신된 페이로드의 무결성과 신뢰성을 보장할 수 있습니다.

Logto와 서비스 간의 연결을 테스트하려면 "테스트 페이로드 전송" 버튼을 클릭하세요. Logto는 선택한 각 이벤트에 대해 샘플 페이로드를 엔드포인트 URL로 전송합니다. 이 테스트 요청에는 익명 데이터가 포함되며, 최근 요청 기록에는 남지 않습니다.

이 테스트를 통해 Webhook이 Logto로부터 페이로드를 정상적으로 수신 및 처리할 수 있도록 올바르게 설정되었는지 확인할 수 있습니다. 실제 환경에 Webhook을 배포하기 전에 통합을 검증할 수 있습니다.

Logto는 Webhook의 상태를 모니터링하고, 잠재적인 문제를 상세히 조사할 수 있는 편리한 도구를 제공합니다:

상태 모니터링 Logto의 Webhook 목록에서는 각 Webhook의 상태, 최근 24시간 동안의 성공률 및 전체 요청 횟수를 확인할 수 있습니다. 이 정보는 Webhook의 성능을 한눈에 파악할 수 있게 해줍니다.
개별 요청 로그 각 Webhook의 "최근 요청" 섹션에서 최근 24시간 동안의 요청 로그를 확인할 수 있습니다. 각 요청이 개별적으로 기록되어, 요청의 세부 정보를 확인하고 잠재적인 오류나 이상 현상을 조사할 수 있습니다.
자동 재시도 전송 실패(응답 상태가 500 이상) 시, Logto는 최대 세 번까지 자동으로 재전송을 시도합니다. 동일한 요청의 여러 번 재시도는 단일 로그 항목만 생성되어 불필요한 중복을 방지합니다. 모든 재시도 요청에는 동일한 deliveryId가 페이로드에 포함되므로, 엔드포인트에서 이미 처리한 전송을 건너뛸 수 있습니다.

이러한 모니터링 기능을 활용하면 Webhook의 상태를 효과적으로 추적하고, 요청 로그를 확인하며, Webhook 통합의 신뢰성과 성능을 보장할 수 있습니다.