[ 25.11.30 ] November API update monthly summary

Summary

November brought reservation send, richer Kakao report detail, message duplicate checks (idempotency), and webhook security verification — updates that substantially strengthen operational stability and developer convenience.

At a glance

• Message duplicate checks (idempotency) are now available
• Security verification headers on report webhooks
• Reservation send is now available (resvSendTime)
• Detailed reasons added to the Kakao report InvalidParameter
• More reliable report processing

What changed?

1. Message duplicate checks (new)

To prevent duplicate message delivery, the idempotencyKey and idempotencyTtl fields have been added.
When the same key arrives within the same window, the server does not process the message twice.

Field description

Allowed values

• Valid range: 1 ~ 86,400 seconds (24 hours)
• Out-of-range or non-numeric input returns an error
• A repeat request with the same idempotencyKey inside the TTL is blocked as a duplicate

2. Security headers on report webhook delivery

Webhook deliveries now carry security headers with a server signature, so you can verify the request has not been tampered with.

Headers provided

How to verify

• On the receiving side, verify with the timestamp provided and the secret you received in advance,
  as follows:

HmacSHA256(secret, timestamp)

※ Customers who need signature verification will receive the secret through a separate channel.

3. Reservation send (new)

A new resvSendTime field lets you send a message automatically at a time you specify.

Reservation management rules

• You can schedule from 10 minutes after the current time
• You can cancel or edit up to 10 minutes before the reservation send time

Field example

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

4. Richer Kakao report failure detail

When an InvalidParameter error occurs, detailed exception information is now included so the cause is clearer.

AS-IS

메시지를 전송할 수 없음

TO-BE

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

• Includes information based on the internal processing trace ID
• Cuts the time it takes both operations and development to find the cause

5. More reliable report processing

• Minimizes the chance of duplication or gaps in the retry logic
• Strengthens handling for customer webhook timeouts
• Adds internal verification steps to reduce the chance of a report going missing during processing

Why it matters

• Message duplicate checks prevent the same message being sent repeatedly after a network retry or an error, which reduces customer cost and operational risk.
• Webhook signatures let you verify that a delivered report has not been tampered with, which strengthens trust in the result data.
• Reservations let customers manage bulk and recurring send schedules more reliably.
• Detailed Kakao report errors let you identify the cause immediately, which speeds up development and operations response considerably.
• More reliable report processing reduces webhook delays and gaps, raising overall message quality and service trust.

How to use it

• We recommend generating the idempotencyKey as a unique value in your own system.
• Verify the Timestamp and Signature values to check the webhook signature.
• A reservation must be set to a time "at least 10 minutes out" to be processed.
• When an InvalidParameter error occurs, the detailed reason lets you analyze the cause immediately.

Things to note

• Keep the webhook secret value in secure storage.
• A reservation can no longer be changed or cancelled inside the last 10 minutes before its reservation send time.
• Reusing an idempotencyKey inside its TTL is treated as a duplicate.
• Webhooks are retried a set number of times depending on network conditions, so plan for duplicate-handling logic.