웹훅

이 문서는 카카오 API 플랫폼에서 제공하는 웹훅(Webhook) 기능을 안내합니다.

기능 소개

웹훅은 서비스 외부에서 발생한 사용자 활동이나 계정 상태 변화에 빠르게 대응할 수 있도록, 카카오 API 플랫폼이 서비스에 HTTP 요청을 전송하는 기능입니다.

카카오 API 플랫폼이 제공하는 웹훅은 아래와 같습니다.

웹훅	설명	관련 제품
연결 끊기 웹훅	사용자 카카오계정과 서비스 앱의 연결이 끊어진 경우, 해당 사용자를 탈퇴 처리할 수 있도록 서비스로 알림 전송	카카오 로그인
계정 상태 변경 웹훅	사용자 계정 상태 변경 이벤트 발생 시, 서비스로 알림 전송	카카오 로그인
카카오톡 공유 웹훅	공유 메시지 전송 성공 시, 서비스로 알림 전송	카카오톡 공유
카카오톡 채널 웹훅	사용자가 서비스의 채널을 추가 또는 차단 시, 서비스로 알림 전송	카카오톡 채널

구현 절차

웹훅 기능을 사용하려면 아래 절차대로 구현해야 합니다.

1. 웹훅 수신 서버 구현

웹훅 요청을 수신하려면 카카오가 전송한 HTTP 요청을 처리할 수 있는 API 엔드포인트를 구현해야 합니다.

엔드포인트 구현 시 아래 사항을 준수해야 합니다.

• 웹훅 요청은 POST 또는 GET 방식으로 전송되며, 이를 수신할 엔드포인트를 구성해야 합니다.
  • (예: https://{SERVICE_DOMAIN}/webhook)
• 카카오는 JSON 또는 URL 쿼리 파라미터 형태의 이벤트 정보롤 포함해 요청을 보내므로, 엔드포인트는 이 요청을 파싱해 처리하는 로직을 구현해야 합니다.
• 웹훅 요청은 HTTPS 프로토콜로 전송되므로, SSL 인증서가 적용된 도메인을 사용해야 합니다.

만약 서비스 서버에서 ACL(Access Control List, 접근 제어 목록)을 관리하는 경우, 웹훅 수신을 위한 IP 허용 설정을 참고합니다.

2. 카카오디벨로퍼스 설정

이전 단계에서 생성한 엔드포인트를 카카오디벨로퍼스에 등록해야 합니다. 아래 문서를 참고해 웹훅 URL을 등록합니다.

• 연결 끊기 웹훅 설정
• 계정 상태 변경 웹훅 설정
• 카카오톡 공유 웹훅 설정
• 카카오톡 채널 웹훅 설정

3. 웹훅 요청 처리

웹훅 이벤트 발생 시, 카카오는 등록된 엔드포인트로 HTTP 요청을 전송합니다.

요청을 수신한 서비스는 아래와 같이 처리해야 합니다.

1. 요청 본문(body)의 페이로드(payload)를 파싱하여 이벤트 정보를 확인합니다.
2. 이벤트 종류에 따라 필요한 후속 작업을 수행합니다. (예: 사용자 탈퇴, 계정 상태 갱신 등)
3. 3초 이내에 웹훅별 응답 규격에 맞는 HTTP 상태 코드로 응답을 반환합니다. (예: 200 OK, 202 Accepted 등) 응답 성공 여부는 상태 코드로 판단되며, 본문(Body)은 필요하지 않습니다.

웹훅 처리를 위해 필요한 작업

웹훅	필요한 작업
연결 끊기 웹훅	1. 서비스 앱 어드민 키와 app_id로 웹훅의 유효성 검증 2. 웹훅이 유효한 경우, user_id에 해당하는 사용자 정보를 개인정보 처리방침과 서비스 정책에 따라 탈퇴 처리, 삭제 또는 기타 방법으로 데이터베이스(DB)에 반영
계정 상태 변경 웹훅	1. 웹훅 요청에 포함된 SET 정보(보안 이벤트 토큰)를 디코딩해 검증 2. 이벤트 타입별 권장 조치 사항 열을 참고해 필요한 조치 사항 구현
카카오톡 공유 웹훅	serverCallbackArgs 정보를 기반으로 서비스 내부 추가 처리(선택)
카카오톡 채널 웹훅	변경된 카카오톡 채널의 추가 또는 차단 상태 업데이트

4. 웹훅 테스트

웹훅 구현 후, 카카오에서 제공하는 웹훅 테스트 도구를 이용해 실제 요청 전송이나 응답 처리를 검증할 수 있습니다. 자세한 사항은 웹훅 테스트를 참고합니다.

이용 정책

필수 응답 규격

모든 웹훅 요청에 대해 서비스 서버는 3초 이내에 정해진 HTTP 상태 코드에 응답해야 합니다. (예: 200 OK, 202 Accepted)

응답 규격은 각 개발 문서의 필수 응답 규격 항목을 참고합니다.

• 연결 끊기 웹훅
• 계정 상태 변경 웹훅
• 카카오톡 공유 웹훅
• 카카오톡 채널 웹훅

상태 코드로 성공 여부를 판단하므로, 응답 본문은 필수 사항이 아닙니다.

웹훅 비활성화

필수 응답 규격에 1개월 이상 응답이 없거나, 높은 오류 발생 빈도가 지속될 경우, 웹훅 기능이 비활성화될 수 있습니다.

연결 끊기 웹훅은 비활성화된 경우, 앱 팀원에게 안내 메일이 발송됩니다. 서비스 상태를 점검한 뒤, 웹훅 설정 페이지에서 활성화 상태를 [사용함]으로 변경해야 합니다.

계정 상태 변경 웹훅은 3시간 이상 연속적인 전송 실패 시, 비활성화 됩니다. 웹훅 설정 페이지에서 활성화 상태를 [사용함]으로 변경해 다시 활성화할 수 있습니다.

웹훅 수신을 위한 IP 허용 설정

서비스 서버에서 ACL(Access Control List, 접근 제어 목록)을 관리하는 경우, 웹훅을 정상적으로 수신하려면 카카오 API 플랫폼의 IP를 허용 목록(Allowlist)에 추가해야 합니다. 방화벽을 참고합니다.

재전송

서비스에서 웹훅 요청을 정상적으로 처리하지 못한 경우, 카카오가 동일 웹훅 이벤트를 다시 발송해 누락된 이벤트를 처리할 수 있도록 재전송 기능을 제공합니다.

이 기능은 현재 계정 상태 변경 웹훅에서만 지원합니다.

재전송 간격

카카오가 보낸 최초의 웹훅 요청에 서비스가 응답하지 않으면, 카카오는 동일 웹훅을 단계별로 재전송합니다.

• 1단계: 5분 간격으로 2회 재전송
• 2단계: 30분 간격으로 2회 재전송
• 3단계: 60분 후 1회 재전송

최초 전송을 포함해 총 6회의 요청이 모두 응답하지 않으면 해당 웹훅은 실패로 처리됩니다.

또는 웹훅 이벤트 발송이 3시간 동안 연속적으로 실패하면 앱의 계정 상태 변경 웹훅이 비활성화됩니다. 이 경우, 남은 재전송 횟수와 관계없이 웹훅 전송이 즉시 중단되고 실패로 간주됩니다.

재활성화

다시 웹훅 요청을 수신하려면 계정 상태 변경 웹훅 페이지에서 웹훅 활성화 상태를 [활성화]로 변경해야 합니다.