메인 콘텐츠로 건너뛰기

보안

웹훅 안정성은 Unico의 전달 보장만큼 엔드포인트 동작에도 달려 있습니다. 이 페이지에서는 엔드포인트가 반드시 준수해야 하는 세 가지 불변 조건인 멱등성, 동시성 제한, 오류율을 다룹니다.

멱등성​

Unico의 웹훅 구현은 최소 한 번 전달을 보장합니다 — 동일한 processId에 대해 동일한 상태가 두 번 이상 알림될 수 있습니다. 엔드포인트는 반드시 멱등성을 가져야 합니다.

권장 패턴:

  1. 모든 웹훅 호출 시 먼저 processId가 이미 처리되었는지 확인하세요.
  2. 이미 처리된 경우, 즉시 2xx를 반환하세요 (작업이 이미 완료됨).
  3. 처리되지 않은 경우, 비즈니스 로직을 적용하고 해당 processId가 처리되었다는 사실을 저장하세요.
// pseudo-code
async function handleWebhook(req, res) {
  const { processId } = req.body;

  if (await alreadyProcessed(processId)) {
    return res.status(200).end();
  }

  await applyBusinessLogic(req.body);
  await markAsProcessed(processId);
  return res.status(200).end();
}
중요한 이유

재시도 시 매번 비즈니스 로직을 실행하는 비멱등 엔드포인트(예: 카드 청구, 이메일 발송)는 재시도가 발생할 때 중복 실행됩니다 — 재시도는 웹훅 전달에서 예외가 아닌 일반적인 동작입니다.

동시성 제한​

대용량 트래픽 기간 동안 엔드포인트를 과부하로부터 보호하기 위해 웹훅 등록 시 최대 동시 처리 중인 전달 수(최대: 500)를 구성하세요.

동시성 제한에 도달하면 Unico는 추가 전달을 대기열에 넣고 용량이 확보되는 대로 처리합니다. 재시도와 결합하면 지속적인 급증 시 새 웹훅의 실질적인 전달 시간이 길어질 수 있습니다.

오류율​

오류율(200–299 범위 외의 응답)은 항상 낮게 유지해야 합니다. 엔드포인트가 대규모로 오류를 반환하기 시작하면 Unico는 해당 엔드포인트에 대한 웹훅 처리량을 자동으로 줄입니다. 재시도 메커니즘과 결합하면 새 웹훅의 실행 시간이 크게 증가할 수 있습니다.

운영 지침:

  • 자체 측에서 non-2xx 응답을 모니터링하세요. 정상 기준치 이상으로 오류율이 지속되면 알림을 설정하세요.
  • 웹훅 핸들러를 중요 경로로 취급하세요 — 스택에서 가장 안정적인 서비스 중 하나여야 합니다.
  • 계획된 유지보수의 경우, 로드 밸런서 단에서 수신을 중단하는 것을 권장합니다. 503을 포함한 지속적인 non-2xx 응답은 위에서 설명한 자동 처리량 제한을 활성화합니다. 엔드포인트가 복구되면 감소된 처리량으로 인해 중단 기간 동안 대기열에 쌓인 이벤트 전달이 지연됩니다. 처리되지 않은 이벤트에 대해 200을 반환하지 마세요.

상태 의미론​

state 및 lastEvent 값의 집합을 진화 가능한 구성으로 취급하세요:

  • 명시적으로 처리하는 상태/이벤트에만 반응하세요.
  • 알 수 없는 값을 로그로 기록하세요 — 오류를 발생시키지 마세요.
  • 주요 버전 변경 없이 새 상태가 추가될 수 있습니다.
마지막 업데이트 에