Node.js(Express)로 KAT Cloud 웹훅 수신 서버 만들기

{
  "eventType": "SEND_RESULT",
  "timestamp": "2024-03-05T10:30:05.000Z",
  "data": {
    "chatId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "chatRoomId": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
    "chatType": "SMS",
    "sendStatus": "SUCCESS",
    "resultStatus": "4100",
    "resultMessage": "전달",
    "sentAt": "2024-03-05T10:30:05.000Z"
  }
}

export KAT_API_KEY="콘솔에서 발급받은 키"
BASE="https://studio-gateway.zerocall.kr"
HOOK_URL="https://hooks.example.com/webhook/katcloud"

for EVENT in MESSAGE_RECEIVED SEND_RESULT CALL_RECEIVED CALL_COMPLETED; do
  curl -s -X POST "$BASE/webhook" \
    -H "x-api-key: $KAT_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"eventType\":\"$EVENT\",\"url\":\"$HOOK_URL\"}"
  echo
done

# 등록된 웹훅 목록(id, eventType, url) 확인
curl -s "$BASE/webhook" -H "x-api-key: $KAT_API_KEY"

// server.js — KAT Cloud 웹훅 수신 서버 (Node.js 18+, Express 4)
const express = require('express');
const { dedupeKey, claim, release } = require('./dedupe');

const app = express();
// CALL_COMPLETED에는 STT 배열이 들어 있어 기본 한도(100kb)를 넘을 수 있다
app.use(express.json({ limit: '2mb' }));

const SUCCESS_CODES = ['4100', '6600', '7000']; // SMS, LMS·MMS, 카카오

const handlers = {
  async MESSAGE_RECEIVED(data) {
    console.log('문자 수신', data.chatRoomId, data.senderPhoneNumber, data.content);
    // 예: 상담 대기열에 넣기, 자동응답 만들기
  },
  async SEND_RESULT(data) {
    const delivered = SUCCESS_CODES.includes(String(data.resultStatus));
    console.log('발송 결과', data.chatId, data.resultStatus, data.resultMessage, delivered);
  },
  async CALL_RECEIVED(data) {
    console.log('착신', data.callHistoryId, data.fromNumber, data.handOffReason || '');
  },
  async CALL_COMPLETED(data) {
    console.log('통화 완료', data.callHistoryId, data.status, data.tag, data.duration);
    // 예: DB 저장, 슬랙 알림, CRM 기록
  },
};

app.post('/webhook/katcloud', (req, res) => {
  const { eventType, data } = req.body || {};

  // 1) 무엇보다 먼저 200을 돌려준다 (타임아웃 10초)
  res.status(200).json({ received: true });

  // 2) 모르는 이벤트나 data가 없는 요청은 조용히 넘긴다
  const handler = handlers[eventType];
  if (!handler || !data) return;

  // 3) 이미 처리한 이벤트면 건너뛴다
  const key = dedupeKey(eventType, data);
  if (key && !claim(key)) return;

  // 4) 실제 처리는 응답 이후에
  setImmediate(async () => {
    try {
      await handler(data);
    } catch (err) {
      if (key) release(key); // 실패하면 다음에 다시 처리할 수 있게 키를 푼다
      console.error('[webhook] 처리 실패', eventType, key, err);
    }
  });
});

app.get('/healthz', (_req, res) => res.send('ok'));

app.listen(process.env.PORT || 3000, () => console.log('webhook server ready'));

// dedupe.js — 이벤트 중복 제거 (단일 프로세스용 메모리 저장소)
const TTL_MS = 24 * 60 * 60 * 1000; // 같은 키를 24시간 기억
const seen = new Map(); // key -> 만료 시각(ms)

// 페이로드에 이벤트 id가 없으므로 data 안의 식별자로 키를 만든다
function dedupeKey(eventType, data = {}) {
  switch (eventType) {
    case 'MESSAGE_RECEIVED':
    case 'SEND_RESULT':
      return data.chatId ? `${eventType}:${data.chatId}` : null;
    case 'CALL_RECEIVED':
      return data.callHistoryId
        ? `${eventType}:${data.callHistoryId}:${data.handOffReason ? 'handoff' : 'ring'}`
        : null;
    case 'CALL_COMPLETED':
      return data.callHistoryId ? `${eventType}:${data.callHistoryId}` : null;
    default:
      return null;
  }
}

// 처음 보는 키면 true(처리), 이미 본 키면 false(건너뜀)
function claim(key) {
  const now = Date.now();
  for (const [k, expiresAt] of seen) {
    if (expiresAt > now) break; // Map은 넣은 순서대로 돌므로 오래된 것부터 정리된다
    seen.delete(k);
  }
  if (seen.has(key)) return false;
  seen.set(key, now + TTL_MS);
  return true;
}

function release(key) {
  seen.delete(key);
}

module.exports = { dedupeKey, claim, release };

SET katcloud:dedupe:CALL_COMPLETED:8f3f8fd9-7ab8-4a26-b523-4f8eb7d38b85 1 NX EX 86400

node server.js

# 다른 터미널에서 같은 요청을 두 번 보낸다
for i in 1 2; do
  curl -s -X POST http://localhost:3000/webhook/katcloud \
    -H "Content-Type: application/json" \
    -d '{"eventType":"SEND_RESULT","timestamp":"2024-03-05T10:30:05.000Z","data":{"chatId":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","chatType":"SMS","sendStatus":"SUCCESS","resultStatus":"4100","resultMessage":"전달"}}'
  echo
done

# webhookId는 GET /webhook 응답의 id
curl -s -X POST "$BASE/webhook/1/test" -H "x-api-key: $KAT_API_KEY"