이벤트 처리

Webhook 이벤트를 안전하고 안정적으로 처리하기 위한 권장 패턴을 설명합니다.

멱등 처리

현재 버전은 자동 재시도 큐를 제공하지 않지만, 운영 중 같은 이벤트가 다시 처리될 가능성에 대비해야 합니다. id 필드를 기준으로 이미 처리한 이벤트인지 확인하고, 중복이면 무시하세요.

const processedIds = new Set<string>()

app.post("/webhooks/bank", (req, res) => {
  const event = req.body

  if (processedIds.has(event.id)) {
    return res.status(200).json({ received: true, duplicate: true })
  }

  processedIds.add(event.id)
  queue.enqueue(event)

  res.status(200).json({ received: true })
})

이벤트 순서

Webhook 도착 순서만으로 최종 상태를 판단하지 마세요. created_at이나 리소스의 최신 상태를 API로 다시 조회하여 순서에 의존하지 않는 로직을 작성하세요.

처리 절차 권장 순서

1. 서명을 검증합니다 (보안 검증 문서 참고).
2. 이벤트 ID로 중복 여부를 확인합니다.
3. 즉시 200 응답을 반환합니다.
4. 실제 비즈니스 로직은 별도 큐나 백그라운드 작업으로 처리합니다.