웹훅
HTTPS 엔드포인트로 전송되는 이벤트입니다. 전송 확인 보고서, 수신 메시지, 상태 변경을 전달하며, 수신 측은 이를 검증하고 빠르게 응답한 뒤 대기열에 넣어야 합니다.
정의만 제공합니다. 여기에서 설명하는 용어는 당사가 판매하는 서비스가 아닙니다.
웹훅은 전송 확인 보고서나 수신 메시지 같은 이벤트를 미리 등록한 URL로 POST하는 HTTPS 콜백입니다. 수신 측은 서명을 검증하고, 2xx로 응답한 뒤 작업을 대기열에 넣습니다.
웹훅은 푸시 방식의 전달이므로, 수신 측이 중복 이벤트와 순서가 뒤바뀐 이벤트를 처리해야 합니다.
검증, 응답, 대기열 처리
이벤트가 발생하면 제공자가 POST를 보내고, 엔드포인트는 2xx를 반환하여 수신을 확인합니다. 페이로드는 보통 이벤트 유형과 식별자를 담은 JSON입니다. 제공자가 페이로드에 서명할 수 있습니다. 공유 비밀 키로 원본 본문과 서명을 대조하고, 재전송 허용 시간 범위를 벗어난 요청은 거부하십시오.
먼저 검증하고, 원본 이벤트를 저장한 뒤, 2xx를 반환하고 작업은 비동기로 처리하십시오. 엔드포인트가 느리면 재시도가 발생합니다. 전달은 보통 최소 1회(at least once) 방식이며 순서가 보존되지 않으므로, 이벤트 ID로 중복을 제거하십시오. 처리할 수 없는 이벤트를 위한 데드 레터 대기열을 두십시오. SMPP와 HTTP 비교 설명에서 콜백과 세션 기반 전달을 비교합니다.
자주 묻는 질문
웹훅과 API는 어떻게 다릅니까?
API는 보통 클라이언트가 가져오는(pull) 방식입니다. 웹훅은 이벤트가 발생할 때 제공자가 밀어 주는(push) 방식이며, 대부분의 플랫폼은 두 가지를 모두 제공합니다.
이벤트가 왜 두 번 도착합니까?
전달은 보통 최소 1회 방식이므로, 재시도로 인해 이미 처리한 이벤트가 중복될 수 있습니다. 이벤트 ID로 중복을 제거하십시오.
어떤 상태 코드를 반환해야 합니까?
이벤트를 저장하거나 대기열에 넣은 후 2xx를 반환하십시오. 그보다 먼저 2xx를 반환하면 다음 단계가 실패할 때 이벤트를 잃을 위험이 있습니다.