웹훅 테스트 없이 배포하면 두 번 실행됩니다

웹훅 중복 실행 경고 일러스트

작성자

카테고리:

테스트 없이 웹훅 켜면 무슨 일이 생기나

웹훅 자동화 테스트하는 방법을 검색하고 있다면, 지금 배포 버튼 앞에서 손이 멈춰 있을 확률이 높다. 나도 그랬다. 코드는 다 짰는데 이걸 실서버에 붙이는 순간 뭔가 잘못되면 어쩌지 하는 생각에 며칠을 미뤄본 적이 있다.

그리고 미루다 그냥 켰다가 새벽에 같은 알림이 두 번씩 가는 걸 목격한 적도 있다. 이 이야기는 뒤에서 다시 한다.

가장 흔한 사고: 같은 이벤트가 두 번 실행됨

웹훅은 보내는 쪽이 “응답이 느리네?” 하면 재시도를 한다. 내 서버는 느렸고, 상대는 다시 보냀고, 나는 두 요청을 각각 정상 이벤트로 받아들여서 같은 처리를 두 번 했다. 결제 webhook이나 알림 트리거에서 이게 터지면 골치가 아프다. 두 번 실행은 버그가 아니라 웹훅의 설계상 기본 동작에 가깝다. 재시도 정책이 있는 이상, 중복 수신은 언제든 일어난다고 가정하고 만들어야 한다.

실패했을 때 아무도 알려주지 않는 문제

더 무서운 쪽은 이거다. 테스트 없이 켰는데 로직이 조용히 죽으면, 보내는 쪽은 재시도 몇 번 하다 포기하고, 내 쪽에는 실패 기록조차 제대로 안 남는다. 나는 며칠 뒤에 로그를 보고서 “아, 이때부터 안 돌았구나”를 알았다. 안 켜는 게 답은 아니다. 격리해서 켜는 게 답이다. 그 흐름을 정리해둔다.

실서버 말고 웹훅을 격리해서 테스트하는 법

테스트 전용 엔드포인트와 스테이징 URL 분리

같은 코드를 스테이징에서 돌린다. 원클립AI 쪽 자동화는 스테이징 도메인을 별도로 파서, 웹훅 수신 URL을 prod가 아니라 staging으로 등록받는 구성으로 운영했다. 코드는 같으니 스테이징에서 통과하면 프로덕션에서도 로직은 같게 도는 것을 확인할 수 있다. 환경설정 값(디비 연결, 슬랙 채널, 실제 결제 키)만 다르게 잡는다.

로컬에서 ngrok·터널로 받아보기

외부에서 로컬 개발 서버로 웹훅을 보내고 싶으면 터널을 쓴다. ngrok이나 cloudflared 같은 걸 띄워서 로컬 포트에 공개 URL을 하나 뚫고, 그 URL을 테스트 webhook 엔드포인트로 등록한다. 로컬에서 브레이크포인트 잡고 한 스텝씩 디버깅할 수 있어서, 처음 붙이는 웹훅이라면 이 단계를 거치는 편이다.

무료 테스트 사이트의 한계

webhook.site 같은 서비스로 “요청이 오는지”는 확인할 수 있다. 근데 그걸로 끝이다. 요청 바디가 어떻게 생겼는지 보여줄 뿐, 내 로직이 그 페이로드를 잘 처리하는지는 아무것도 말해주지 않는다. 경쟁 글들이 대부분 여기서 끝나는데, 실전에서 중요한 건 그 다음이다.

실제 페이로드를 잡아서 그대로 재현하는 방법

샘플 JSON 대신 진짜 이벤트 로그 남기기

문서에 있는 샘플 JSON은 함정이다. 실제 이벤트는 필드가 더 많거나, 어떤 필드는 null이거나, 배열이 비어 있거나 한다. 그래서 나는 웹훅을 수신하는 모든 핸들러 첫 줄에서 원본 페이로드를 그대로 저장한다. 스토리지에 JSON 파일로든, 테이블 한 줄로든, 일단 원문을 남긴다. 이게 지금도 유지하는 습관이다.

// 수신 즉시, 파싱 전에 원문 저장
$body = file_get_contents('php://input');
file_put_contents(
  __DIR__."/logs/webhook-".date('Ymd-His')."-".bin2hex(random_bytes(4)).".json",
  $body
);

파싱하기 전에 저장해야 한다. 파싱하다 죽은 요청도 원문은 남아 있어야 나중에 무엇이 들어왔는지 볼 수 있다.

캡처한 페이로드로 리플레이 테스트 돌리기

이제 테스트는 단순해진다. 저장해둔 JSON을 스테이징 엔드포인트에 그대로 다시 POST한다.

curl -X POST https://staging.example.com/webhook/payment \
  -H "Content-Type: application/json" \
  -d @webhook-20261018-0312-a1b2.json

실제 서비스에서 왔던 진짜 데이터로 내 로직을 몇 번이고 다시 돌릴 수 있다. 샘플로 테스트해서 통과했는데 실 이벤트에서 필드 하나가 달라서 죽는, 그 지점을 미리 잡을 수 있다.

타임스탬프·토큰처럼 재현 시 조심할 필드들

리플레이할 때 주의할 게 있다. 페이로드 안의 타임스탬프나 서명 토큰은 발행 시점이 과거라 서명 검증이 실패할 수 있다. 나는 리플레이 테스트에서는 서명 검증 단계를 스킵하거나 완화하는 플래그를 두고, 진짜 배포 전에는 그 플래그를 끄고 새 이벤트로 한 번 더 확인한다. 서명 검증을 꺼둔 채 배포하는 사고가 생기지 않게, 플래그가 켜져 있으면 로그에 크게 경고를 남기게 해뒀다.

웹훅 격리 테스트 방법 그림

실패와 중복 호출을 막는 안전장치

멱등성 키: 같은 이벤트는 한 번만 실행되게

새벽에 같은 알림이 두 번 갔던 사고를 복기하니 원인은 명확했다. 상대쪽 재시도를 나는 별개 요청으로 처리했다. 고친 방법은 이벤트 ID 저장이다. 페이로드에 이벤트 고유 ID가 있으면, 처리 전에 그 ID가 이미 처리됐는지 확인하고 끝났던 적이 있으면 바로 성공 응답만 돌려준다.

$eventId = $payload['id'] ?? null;
$lockKey = "webhook:done:{$eventId}";

if ($redis->get($lockKey)) {
    http_response_code(200); // 이미 처리했음, 재시도에 대한 응답만
    exit;
}

// 처리 시작 전에 락 획득 시도 (NX: 없을 때만 설정)
if (!$redis->set($lockKey, '1', ['nx', 'ex' => 86400])) {
    http_response_code(200);
    exit;
}

// ... 실제 처리 ...

관점을 바꿔야 한다. 중복 수신 자체를 막는 건 불가능에 가깝다. 막는 게 아니라, 두 번 받아도 효과는 한 번만 나게 만드는 것. 그게 멱등성이다. redis 대신 그냥 테이블에 이벤트 ID를 unique 키로 넣고 INSERT가 실패하면 스킵하는 방법도 쓸 수 있다. 서버가 한 대면 그걸로 충분하다.

재시도·타임아웃 동작 이해하고 받아들이기

내 핸들러가 5초 넘게 걸리면 상대는 타임아웃으로 보고 재시도한다. 그러면 같은 이벤트가 또 들어온다. 그래서 수신 즉시 200을 주고 실제 처리는 큐나 크론으로 미루는 구성으로 바꿨다. 응답은 빠르게, 처리는 나중에. 이걸 바꾼 뒤로 재시도 때문에 겹치는 일 자체가 눈에 띄게 줄었다.

실패 알림 채널과 수동 재처리 흐름

처리가 실패하면 알림이 오게 해뒀다. 실패한 이벤트는 별도 테이블에 쌓아두고(데드레터 역할), 나는 그걸 슬랙 알림으로 받고 원인 고친 뒤 리플레이와 같은 방식으로 다시 POST해서 수동 재처리한다. 앞서 원문 페이로드를 다 저장해두니까 실패한 이벤트도 언제든 다시 돌릴 수 있다. 되돌리기는 “자동 롤백” 같은 화려한 게 아니라, 실패분을 모아뒀다가 고쳐서 다시 돌리는 이 흐름이면 1인 운영에서는 충분히 돌아간다.

솔직하게 말하면 멱등성 키로도 못 막는 게 남아 있다. 같은 이벤트의 두 번째 재시도가 첫 처리가 끝나기 전에 도착하면 순서가 뒤바뀌는 케이스다. 이건 아직 완전히 안 풀렸고, 지금은 “이벤트 생성 시각”을 비교해서 오래된 것은 버리는 정도로 임시로 막고 있다.

실제 페이로드 재현 테스트 삽화

테스트 데이터와 실데이터를 구분하는 법

더미 사용자·더미 상품 계정 운영하기

스테이징에서 테스트할 때는 실제 사용자 데이터를 건드리면 안 된다. 나는 테스트 전용 더미 계정을 몇 개 만들어두고, 스테이징 웹훅의 대상 ID는 그 계정들로만 향하게 설정한다.

플래그와 DB 분리의 트레이드오프

이상적으로는 스테이징 디비를 아예 분리하는 건데, 1인 운영으로 서비스 7개를 굴리다 보면 DB까지 나누는 게 매번 현실적으로 되지는 않는다. 그래서 어떤 서비스는 test_mode 플래그로 처리 대상을 필터링하는 방식으로 버텼다. 웹훅 핸들러가 test_mode면 더미 계정에만 쓰고, 실제 사용자 레코드에는 쓰지 않게 가드를 거는 식이다.

이 방식의 한계도 분명하다. 가드를 잘못 걸면 실데이터가 흘러들어온다. 그래서 test_mode가 아닐 때 더미 계정에 쓰려고 하면 에러를 내도록 반대 방향 가드도 넣었다. 양방향으로 못 넘어가게 해두는 편이다.

너무 나누면 테스트를 안 하게 된다

환경 분리를 지나치게 정교하게 만들면 세팅이 귀찮아져서 오히려 테스트 자체를 안 하게 된다. 나는 그 중간 어딘가에서 타협한다. 쓰기 경로에 가드 두 개, 나머지는 플래그 하나로 충분하다고 본다.

배포 전 체크리스트 안전장치 이미지

배포 직전 5분 체크리스트

실제로 내가 배포 전에 보는 항목 그대로다. 이 표 하나만 즐겨찾기해도 된다.

체크 확인할 것
리플레이 통과 캡처해둔 실 페이로드로 스테이징에서 처리 성공
중복 방어 같은 이벤트 ID를 두 번 보내도 처리는 한 번만 되는지
서명 검증 켜짐 테스트용 완화 플래그가 꺼져 있는지
실패 알림 도착 일부러 실패시켜서 알림이 오는지 한 번 확인
킬 스위치 문제 생겼을 때 웹훅 처리를 플래그 하나로 끌 수 있는지

첫 실 이벤트 들어올 때 지켜보는 자세

켠 직후에는 로그를 눈으로 지켜본다. 첫 이벤트가 들어오면 원문 페이로드가 쌓이는지, 처리가 끝나는지, 멱등성 키가 저장되는지를 실시간으로 본다. 몇 개 정도 정상 흐름을 눈으로 확인하고 나서야 자리를 뜬다.

문제가 터졌을 때 끄고 되돌리는 절차

  1. 킬 스위치로 새 처리 즉시 중단 (수신은 계속, 원문은 계속 저장되게 둔다)
  2. 원인 파악, 스테이징에서 리플레이로 재현
  3. 고친 뒤 실패분(데드레터)을 낡은 것부터 수동 재처리
  4. 킬 스위치 다시 켜고 첫 이벤트 직접 지켜보기

원문 저장을 계속 살려두는 게 포인트다. 처리를 멈춰도 이벤트를 잃지 않으니, 끄는 결정이 덜 무섭다.

정리: 웹훅은 무서워서 끄는 게 아니라 격리해서 켜는 것이다

질문 다섯 개에 한 줄씩 답하면 이렇다. 실서버 직결 대신 같은 코드를 스테이징에서 돌린다. 샘플이 아니라 실제 이벤트 원문을 저장해 리플레이한다. 중복 실행은 이벤트 ID 저장으로 한 번만 효과가 나게 만든다. 테스트 데이터는 더미 계정과 플래그로 격리한다. 배포 전에는 위 체크리스트를, 배포 후에는 첫 이벤트를 눈으로 본다.

오늘 당장 30분 안에 할 수 있는 건 하나다. 지금 운영 중인 웹훅 핸들러 첫 줄에 원문 페이로드 저장 한 줄을 넣는 것. 이거 하나만 있어도 다음 테스트 전부가 리플레이로 돌아간다.

잘된 것도 망한 것도 기록으로 남기는 이유는 단순하다. 새벽에 알림 두 번 갔던 그 날의 나 같은 사람이, 다음에는 로그 먼저 보고 켤 수 있게. 이 블로그의 자동화 이야기는 OneClip 쪽 서비스 운영과 같이 계속 쌓이고 있다.


글쓴이 정보

혼자 자동화로 서비스를 굴리는 아일리고입니다. 숏폼 영상은 제가 만든 ClipSquare 로 뽑습니다.