외부 이벤트 API 응답이 예상과 다를 때

외부 서비스의 이벤트를 처리하는 엔드포인트가 갑자기 에러를 내거나 예상한 데이터가 없을 때가 있다. 특히 타사 서비스가 API를 업데이트했다거나 요청 형식이 바뀌었을 때 발생한다.

실제 이벤트 페이로드 확인하기

외부 서비스에서 오는 이벤트를 그대로 로그에 출력한다. 이를 통해 예상한 형식과 실제 형식의 차이를 본다.

// Express 예제
app.post('/webhooks/event', (req, res) => {
  console.log('Event received:', JSON.stringify(req.body, null, 2));
  console.log('Headers:', req.headers);
  // 처리 로직
  res.json({ success: true });
});

에러 메시지 확인

애플리케이션 로그에서 구체적인 에러 메시지를 찾는다. "Cannot read property" 같은 메시지는 응답 구조가 예상과 다르다는 신호다.

sudo journalctl -u your-app -n 100 | grep -i error

테스트 이벤트 전송하기

외부 서비스가 제공하는 테스트 기능을 사용해서 샘플 이벤트를 보낸다. Webhook 서비스 대부분이 "Send test event" 버튼을 제공한다.

テストから送られたペイロードを確認して、以下をチェックします:

• 필드명 (camelCase vs snake_case)
• 데이터 타입 (문자열 vs 숫자)
• 중첩 객체의 구조

API 문서와 비교

외부 서비스의 공식 문서를 다시 확인한다. 특히 최근 변경사항이 있는지 확인해야 한다.

// 예상한 구조
{
  event: 'order.created',
  data: {
    orderId: 123,
    amount: 100,
  },
}

// 실제 구조 (필드명이 다를 수 있음)
{
  type: 'order.created',
  payload: {
    order_id: '123', // snake_case이고 문자열
    total_amount: '100.00', // 다른 필드명, 문자열
  },
}

응답 본문 검증

응답 데이터의 존재 여부와 타입을 먼저 확인한 후 처리한다.

app.post('/webhooks/event', (req, res) => {
  const { type, payload } = req.body;

  // 필드 존재 확인
  if (!type || !payload) {
    console.error('Missing required fields');
    return res.status(400).json({ error: 'Invalid payload' });
  }

  // 타입별 처리
  if (type === 'order.created') {
    const orderId = payload.order_id || payload.orderId;
    if (!orderId) {
      console.error('Order ID is missing');
      return res.status(400).json({ error: 'Order ID required' });
    }
    // 처리
  }

  res.json({ success: true });
});

버전별 처리

외부 API가 여러 버전을 지원한다면, 요청 헤더나 URL에서 버전을 확인하고 그에 맞게 처리한다.

app.post('/webhooks/event', (req, res) => {
  const apiVersion = req.headers['x-api-version'] || '1.0';

  if (apiVersion === '1.0') {
    // 이전 형식으로 처리
    const orderId = req.body.orderId;
  } else if (apiVersion === '2.0') {
    // 새로운 형식으로 처리
    const orderId = req.body.payload.order_id;
  }
});

모니터링 추가

장기적으로는 이벤트 응답을 모니터링해서 형식이 변할 때 알림을 받도록 설정한다.

// 월별 이벤트 통계
if (!KNOWN_EVENT_TYPES.includes(type)) {
  logger.warn(`Unknown event type received: ${type}`, req.body);
}

체크리스트

1. 실제 이벤트 페이로드를 로그에 출력한다.
2. 에러 메시지의 구체적인 내용을 확인한다.
3. 외부 서비스의 테스트 이벤트를 보내서 샘플을 확인한다.
4. 공식 API 문서의 최신 버전을 확인한다.
5. 응답 필드의 존재 여부와 타입을 검증한다.
6. API 버전별로 다르게 처리한다면 버전을 확인한다.
7. 미지의 이벤트 타입을 로깅한다.

외부 API 응답 문제는 직접 확인하는 것이 가장 빠르다. 로그 출력과 테스트 이벤트를 활용하면 대부분의 문제를 쉽게 해결할 수 있다.