search
Ctrlk
비즈고 바로가기

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

hashtag
한줄 요약

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

hashtag
한눈에 보기

  • 메시지 중복 체크(Idempotency) 기능 신규 제공

  • 리포트 Webhook 보안 검증 헤더 제공

  • 예약 발송 기능 신규 제공 (resvSendTime)

  • 카카오 리포트 InvalidParameter 상세 사유 추가

  • 리포트 처리 안정성 개선

hashtag
무엇이 달라졌나요?

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

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

필드 설명

필드
설명

idempotencyKey

중복 여부 판단을 위한 고유 키

idempotencyTtl

중복 허용 시간(초 단위, TTL)

허용 조건

  • 유효 범위: 1 ~ 86,400초(24시간)

  • 범위 초과 또는 비숫자 입력 시 오류 반환

  • TTL 시간 내 동일 idempotencyKey 재요청 시 중복 처리 방지

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

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

제공 헤더

헤더명
설명

X-IB-Timestamp

Webhook 전송 시점(timestamp). 서명 원문에 포함

X-IB-Signature

HmacSHA256(secret, timestamp)로 생성된 서명값

검증 방식

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

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

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

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

예약 조건

  • 현재 시각 기준 10분 후부터 예약 가능

  • 예약 발송 10분 전까지 취소/수정 가능

필드 예시

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

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

AS-IS

TO-BE

  • 내부 처리 Trace ID 기반 정보 포함

  • 운영/개발 모두 문제 원인 파악 시간이 크게 단축됨

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

  • 재시도 로직의 중복 및 누락 발생 가능성을 최소화

  • 고객사 Webhook Timeout 대응 로직 보강

  • 메시지 처리 중 리포트 누락 가능성을 줄이기 위한 내부 검증 절차 강화

hashtag
왜 중요한가요?

  • 메시지 중복 체크 기능은 네트워크 재시도나 오류 상황에서도 동일 메시지가 반복 발송되는 사고를 방지해 고객 비용과 운영 리스크를 줄여줍니다.

  • Webhook 보안 서명 기능은 전달되는 리포트가 위변조되지 않았음을 검증할 수 있어 메시지 결과 데이터의 신뢰성을 강화합니다.

  • 예약 발송을 통해 고객사는 대량·정기 발송 스케줄을 보다 안정적으로 관리할 수 있습니다.

  • 카카오 리포트 오류 상세화는 문제 발생 시 원인을 즉시 파악할 수 있어 개발·운영 대응 속도를 크게 향상시킵니다.

  • 리포트 처리 안정성 개선은 Webhook 지연·누락 가능성을 줄여 전체 메시지 운영 품질과 서비스 신뢰도를 높여줍니다.

hashtag
이렇게 사용하세요

  • idempotencyKey는 고객사 시스템에서 유일값 생성을 권장합니다.

  • Webhook 서명 검증을 위해 Timestamp·Signature 값을 검증해 주세요.

  • 예약 발송은 “10분 이후” 시간으로 설정해야 정상 처리됩니다.

  • InvalidParameter 오류 발생 시 상세 사유를 기반으로 즉시 원인 분석이 가능합니다.

hashtag
유의사항

  • Webhook secret 값은 반드시 안전한 저장소에 보관해야 합니다.

  • 예약 발송은 예약시간 10분 전 이후로는 변경/취소가 불가합니다.

  • idempotencyKey는 TTL 내 재사용될 경우 중복 처리로 판단됩니다.

  • Webhook 재시도는 네트워크 상태에 따라 일정 횟수까지 수행되므로, 중복 처리 방지 로직을 고려해 주세요.

이전[ 25.11.12 ] 발송 내역 개편다음[ 25.10.21 ] 비즈플러스 고객 전환

마지막 업데이트