[ 25.11.30 ] 11월 API 업데이트 월간 요약

한줄 요약

11월에는 예약 발송 기능, 카카오 리포트 상세 정보 강화, 메시지 중복 체크(idempotency) 기능, Webhook 보안 검증 기능 등 메시지 운영 안정성과 개발 편의성을 대폭 강화하는 업데이트들이 제공되었습니다.

한눈에 보기

• 메시지 중복 체크(Idempotency) 기능 신규 제공
• 리포트 Webhook 보안 검증 헤더 제공
• 예약 발송 기능 신규 제공 (resvSendTime)
• 카카오 리포트 InvalidParameter 상세 사유 추가
• 리포트 처리 안정성 개선

무엇이 달라졌나요?

1. 메시지 중복 체크 기능 추가 (신규)

중복 메시지 전송을 방지하기 위해 idempotencyKey, idempotencyTtl 필드가 새로 추가되었습니다.
동일한 key로 동일 시간 내 요청 시 서버는 메시지를 중복 처리하지 않습니다.

필드 설명

허용 조건

• 유효 범위: 1 ~ 86,400초(24시간)
• 범위 초과 또는 비숫자 입력 시 오류 반환
• TTL 시간 내 동일 idempotencyKey 재요청 시 중복 처리 방지

2. 리포트 Webhook 전달 시 보안 확인 헤더 추가

Webhook 전달 시 요청 위변조 및 신뢰성 검증을 위해 서버 서명을 포함한 보안 헤더가 제공됩니다.

제공 헤더

검증 방식

• 서버 수신 측은 제공된 timestamp와 사전에 전달받은 secret으로
  아래 방식으로 검증 가능:

HmacSHA256(secret, timestamp)

※ 서명 검증이 필요한 고객사에는 secret을 별도 채널로 전달할 예정입니다.

3. 예약 발송 기능 추가 (신규)

새로운 필드 resvSendTime이 추가되어 지정한 시간에 메시지를 자동 발송할 수 있습니다.

예약 조건

• 현재 시각 기준 10분 후부터 예약 가능
• 예약 발송 10분 전까지 취소/수정 가능

필드 예시

"resvSendTime": "2025-11-25T10:20:00+09:00"

4. 카카오 리포트 실패 상세내용 고도화

InvalidParameter 오류가 발생한 경우, 보다 명확한 원인을 확인할 수 있도록 상세 Exception 정보가 추가되었습니다.

AS-IS

메시지를 전송할 수 없음

TO-BE

메시지를 전송할 수 없음(NoSendAvailableException(20251120-sn-r-0132645416POM028018629000))

• 내부 처리 Trace ID 기반 정보 포함
• 운영/개발 모두 문제 원인 파악 시간이 크게 단축됨

5. 리포트 처리 안정성 개선

• 재시도 로직의 중복 및 누락 발생 가능성을 최소화
• 고객사 Webhook Timeout 대응 로직 보강
• 메시지 처리 중 리포트 누락 가능성을 줄이기 위한 내부 검증 절차 강화

왜 중요한가요?

• 메시지 중복 체크 기능은 네트워크 재시도나 오류 상황에서도 동일 메시지가 반복 발송되는 사고를 방지해 고객 비용과 운영 리스크를 줄여줍니다.
• Webhook 보안 서명 기능은 전달되는 리포트가 위변조되지 않았음을 검증할 수 있어 메시지 결과 데이터의 신뢰성을 강화합니다.
• 예약 발송을 통해 고객사는 대량·정기 발송 스케줄을 보다 안정적으로 관리할 수 있습니다.
• 카카오 리포트 오류 상세화는 문제 발생 시 원인을 즉시 파악할 수 있어 개발·운영 대응 속도를 크게 향상시킵니다.
• 리포트 처리 안정성 개선은 Webhook 지연·누락 가능성을 줄여 전체 메시지 운영 품질과 서비스 신뢰도를 높여줍니다.

이렇게 사용하세요

• idempotencyKey는 고객사 시스템에서 유일값 생성을 권장합니다.
• Webhook 서명 검증을 위해 Timestamp·Signature 값을 검증해 주세요.
• 예약 발송은 “10분 이후” 시간으로 설정해야 정상 처리됩니다.
• InvalidParameter 오류 발생 시 상세 사유를 기반으로 즉시 원인 분석이 가능합니다.

유의사항

• Webhook secret 값은 반드시 안전한 저장소에 보관해야 합니다.
• 예약 발송은 예약시간 10분 전 이후로는 변경/취소가 불가합니다.
• idempotencyKey는 TTL 내 재사용될 경우 중복 처리로 판단됩니다.
• Webhook 재시도는 네트워크 상태에 따라 일정 횟수까지 수행되므로, 중복 처리 방지 로직을 고려해 주세요.