결제 알림이 두 번 오면 무엇이 꼬이는가
결제 알림이 두 번 들어왔을 때 제일 먼저 드는 걱정은 고객이 돈을 두 번 낸 것처럼 보이는 상황이다. 주문 상태가 어긋나고, 구독 기간이 두 번 늘어나고, 그러다 고객 문의가 온다. 웹훅 중복 수신이란 PG사가 같은 결제 이벤트를 우리 서버에 한 번 넘게 보내서, 같은 처리가 여러 번 실행되는 상황을 말한다.
아래는 월 구독 상품 하나를 놓고 뜯어본 사례다. 실제 장애 로그를 가져온 것이 아니라, 구조상 이런 일이 어떻게 생기는지 따라가 본 것이다.
주문은 이미 결제 완료인데 구독 기간이 두 번 연장되는 경우
승인 알림을 받으면 핸들러가 구독 만료일을 구독 기간만큼 뒤로 민다. 같은 승인 알림이 두 번 들어오면 만료일도 두 번 밀린다. 주문 상태는 ‘결제 완료’로 덮어쓰는 방식이라 두 번 써도 겉으로 티가 안 난다. 구독은 만료일이 계산으로 누적되니까 고객 입장에서는 기간을 두 번 산 셈이 된다.
두 번 처리되면 보이는 증상
- 구독 만료일이 실제 결제 주기보다 길게 잡힌다.
- 주문은 완료인데 적립금이나 잔액이 두 번 반영된다.
- 고객 화면과 관리자 화면 상태가 다르다. 한쪽은 취소, 다른 쪽은 결제 완료로 남는다.
지금 확인할 것과 나중에 고쳐도 되는 것
당장 봐야 하는 건 돈과 권한에 닿는 것이다. 구독 만료일, 잔액, 결제 완료 여부가 여기에 든다. 알림 메일이 두 번 나간 것이나 로그 문구 중복은 나중에 고쳐도 된다. 나는 DB를 열기 전에 이 목록부터 만든다. 순서를 정해두지 않으면 로그만 보다가 하루가 간다.
웹훅은 왜 같은 이벤트를 두 번 이상 보내는가
PG사 입장에서 웹훅은 응답이 와야 성공이다. 응답이 늦거나 실패하면 같은 이벤트를 다시 보낸다. 그래서 중복이 생기면 PG사 탓부터 하기 쉬운데, 우리 쪽 응답이 느린 것이 원인인 경우가 많았다.
응답 타임아웃과 재시도
수신 핸들러 안에서 외부 API 호출이 끝날 때까지 응답을 미루면 PG사 타임아웃에 걸린다. PG사는 실패로 보고 재전송하는데, 우리 서버는 처음 요청을 아직 처리하고 있을 수 있다. 두 요청이 겹치는 그 순간이 중복이 생기는 자리다.
[webhook] recv provider=pg event_key=evt_9f2c type=payment.approved handler=sync_external_call result=timeout
이 한 줄이 남으면 응답 시간과 처리 시간이 같은 줄에 있는지부터 본다. 이걸 보기 전에 PG사를 탓하지 않는다.
네트워크 중간 실패와 5xx
처리는 끝났는데 응답 직전에 연결이 끊기면 PG사는 실패로 판단한다. 우리가 5xx를 줘도 같은 재전송이 온다. 우리 로그에는 처리 완료, PG 쪽에는 실패로 남는 어긋남이 생긴다.
순서 역전과 지연 도착
승인 알림보다 취소 알림이 먼저 도착하는 일도 있다. 이때 승인을 나중에 처리하면 취소된 결제가 다시 완료 상태로 돌아간다. 중복 키로는 이 문제가 안 막힌다. 상태가 어떤 순서로 바뀌어야 하는지 따로 검사해야 한다.
중복을 판별할 고유 키는 무엇으로 정하는가
1순위는 PG사가 주는 이벤트 ID다. 재전송에도 같은 값이 오면 이 값 하나로 충분하다. 문제는 이벤트 ID가 없거나 재전송마다 값이 바뀌는 경우다. PG사마다 이 필드가 달라서, 이름별 비교표는 뺐다. 내가 확인한 문서 범위가 좁아서 틀린 표를 올릴 수 없었다.
| 키 후보 | 안정성 | 주의점 |
|---|---|---|
| PG 이벤트 ID | 재전송에도 같은 값이면 가장 안정적 | 재전송 때 값이 유지되는지 PG사 문서와 실제 재전송으로 확인한다 |
| 결제 키 + 이벤트 타입 + 상태 | 이벤트 ID가 없을 때 쓰는 대체 키 | 부분 취소나 재결제에서 같은 조합이 다른 사건을 가리킬 수 있다 |
| 주문 번호 단독 | 불안정 | 같은 주문에 부분 취소가 붙으면 두 번째 사건이 첫 번째 사건과 같은 키로 걸러진다 |
| 결제 키 단독 | 상태 변화를 구분 못 함 | 승인과 취소가 같은 결제 키를 공유한다 |
주문 번호 하나로 막으면 바로 사고가 난다. 승인 알림을 처리한 뒤 같은 주문에 부분 취소가 들어오면, 취소 알림이 승인과 같은 키로 보여서 버려진다. 취소가 반영되지 않은 채 주문이 남는다.

처리 기록 테이블은 어떤 컬럼으로 설계하는가
처음에는 처리 완료 여부 boolean 하나면 되겠다 싶다. 나는 이렇게 시작하지 않는다. 처리 중, 실패, 완료가 모두 false로 보이면 재처리를 해야 할지 판단할 수 없기 때문이다.
CREATE TABLE payment_webhook_event (
id BIGSERIAL PRIMARY KEY,
provider VARCHAR(32) NOT NULL,
event_key VARCHAR(128) NOT NULL,
event_type VARCHAR(64) NOT NULL,
payment_key VARCHAR(128) NOT NULL,
status VARCHAR(16) NOT NULL DEFAULT 'received',
attempt_count INT NOT NULL DEFAULT 0,
payload_hash CHAR(64) NOT NULL,
received_at TIMESTAMPTZ NOT NULL DEFAULT now(),
locked_at TIMESTAMPTZ,
processed_at TIMESTAMPTZ,
last_error TEXT,
CONSTRAINT uq_webhook_event UNIQUE (provider, event_key),
CONSTRAINT ck_webhook_status CHECK (status IN ('received', 'processing', 'done', 'failed'))
);
CREATE INDEX ix_webhook_status_received ON payment_webhook_event (status, received_at);
CREATE INDEX ix_webhook_payment ON payment_webhook_event (provider, payment_key);
이 DDL은 PostgreSQL 기준이다. MySQL이면 타입과 제약 문법을 맞춰야 한다. 컬럼마다 없으면 생기는 문제를 적어둔다.
- provider, event_key: 유니크 제약이 있어야 동시에 들어온 두 건 중 하나만 들어간다. 없으면 같은 건이 두 줄 생긴다.
- event_type: 승인인지 취소인지 구분한다. 없으면 상태 순서 검사를 못 한다.
- payment_key: 같은 결제에 다른 event_key가 붙은 중복을 찾는 기준이다. 뒤에서 나올 탐지 쿼리가 여기에 의존한다.
- status: 실패 건을 재처리 대상으로 고를 수 없다.
- locked_at: 워커가 죽으면 processing 상태가 영원히 남는다. 이 시각으로 오래 머문 건을 찾는다.
- attempt_count: 같은 실패를 무한 재시도하는지 확인할 수 없다.
- payload_hash: 같은 event_key인데 내용이 다르게 온 경우를 가려낸다.
- received_at, processed_at: 지연과 순서 역전을 판단하는 기준이다.
- last_error: 실패 원인 문자열이다. 이게 없으면 실패 이유를 로그에서 다시 찾아야 한다.
상태값은 네 개다. received는 기록만 있고 처리 전, processing은 워커가 잡은 상태, done은 비즈니스 반영까지 커밋된 상태, failed는 예외로 롤백되고 last_error가 남은 상태다.
중복 방지 로직은 3단계로 어떻게 구현하는가
1단계는 수신 즉시 기록을 넣는 것이다. 기록이 커밋된 뒤에만 200을 준다. 순서를 뒤집으면 응답은 나갔는데 기록이 사라지는 틈이 생긴다. PG사는 성공으로 알고 재전송을 멈춘다.
INSERT INTO payment_webhook_event (provider, event_key, event_type, payment_key, payload_hash)
VALUES ($1, $2, $3, $4, $5)
ON CONFLICT (provider, event_key) DO NOTHING;
-- 영향 행이 0이면 이미 받은 이벤트다. 200으로 응답하고 끝낸다.
2단계는 처리 권한을 잡고, 비즈니스 반영과 상태 완료를 한 트랜잭션으로 묶는 것이다. 처리 권한을 잡는 UPDATE와 트랜잭션을 분리한 이유는 워커가 중간에 죽었을 때 processing으로 남은 건을 다른 워커가 집을 수 있게 하려는 것이다.
-- (a) 처리 권한 잡기
UPDATE payment_webhook_event
SET status = 'processing', locked_at = now(), attempt_count = attempt_count + 1
WHERE provider = $1 AND event_key = $2
AND (status IN ('received', 'failed')
OR (status = 'processing' AND locked_at < now() - make_interval(secs => $3)));
-- 0행이면 이미 done이거나 다른 워커가 처리 중이다. 여기서 끝낸다.
BEGIN;
-- (b) 비즈니스 반영. 같은 event_key가 이미 적용됐으면 0행이 된다.
UPDATE subscription
SET expires_at = expires_at + $4, last_applied_event_key = $2
WHERE id = $5 AND last_applied_event_key IS DISTINCT FROM $2;
-- (c) 완료 표시. 0행이면 권한을 잃은 것이니 ROLLBACK한다.
UPDATE payment_webhook_event
SET status = 'done', processed_at = now(), locked_at = NULL
WHERE provider = $1 AND event_key = $2 AND status = 'processing';
COMMIT;
(b)의 last_applied_event_key 가드가 두 번째 방어선이다. 워커의 잠금 시간이 지나서 다른 워커가 같은 건을 집더라도 비즈니스 반영은 한 번만 일어난다. 이 가드를 빼면 2단계는 사실상 1단계와 같은 역할만 하게 된다.
3단계는 실패 건을 다시 집는 워커다. 수신 핸들러는 INSERT만 하고, 실제 처리는 전부 이 워커가 맡는다.
SELECT provider, event_key
FROM payment_webhook_event
WHERE status IN ('received', 'failed')
OR (status = 'processing' AND locked_at < now() - make_interval(secs => $1))
ORDER BY received_at
LIMIT $2;
주의할 점이 하나 있다. 기록 INSERT와 비즈니스 반영을 순서 없이 나누면 틈이 생긴다. 비즈니스 반영을 먼저 하고 기록을 나중에 넣으면, 그 사이에 죽었을 때 재전송이 와도 기록이 없어서 또 반영된다.

이미 중복된 데이터는 어떻게 찾고 정리하고 복구하는가
키를 막는 건 앞으로의 일이다. 이미 들어간 중복은 따로 찾아서 되돌려야 한다. 정리 스크립트는 자동으로 돌리지 않는다. 손으로 한 번 돌려서 건수를 맞춘 뒤에만 커밋한다. 자동 보정은 고객의 구독 상태를 직접 바꾸기 때문에 잘못 돌리면 되돌리는 데 더 많은 작업이 든다.
SELECT provider, payment_key, event_type, COUNT(*) AS cnt,
MIN(received_at) AS first_at, MAX(received_at) AS last_at
FROM payment_webhook_event
WHERE status = 'done'
GROUP BY provider, payment_key, event_type
HAVING COUNT(*) > 1;
이 쿼리는 event_key가 달라서 유니크 제약을 통과한 중복까지 잡는다. 정상적인 반복 이벤트도 섞여 나오니까 금액과 이벤트 타입을 같이 본다.
구독 연장을 되돌리려면 연장할 때마다 변경 이력을 남기는 테이블이 있어야 한다. 여기서는 subscription_change_log라고 부른다. 이력이 없으면 되돌릴 기준이 없으니, 보정 전에 이 테이블부터 만들어야 한다.
BEGIN;
CREATE TEMP TABLE fix_target AS
SELECT l.id AS log_id, l.subscription_id, l.extend_interval
FROM subscription_change_log l
JOIN (SELECT payment_key, MIN(id) AS keep_id
FROM subscription_change_log
WHERE change_type = 'extend'
GROUP BY payment_key
HAVING COUNT(*) > 1) d
ON d.payment_key = l.payment_key
WHERE l.change_type = 'extend'
AND l.id <> d.keep_id;
SELECT COUNT(*) FROM fix_target; -- 기대 건수와 대조한다
UPDATE subscription s
SET expires_at = s.expires_at - x.total
FROM (SELECT subscription_id, SUM(extend_interval) AS total
FROM fix_target GROUP BY subscription_id) x
WHERE s.id = x.subscription_id;
UPDATE subscription_change_log
SET reverted_at = now()
WHERE id IN (SELECT log_id FROM fix_target);
-- 결과가 맞으면 COMMIT, 이상하면 ROLLBACK
COMMIT;
MIN(id)를 남기는 방식은 가장 먼저 들어간 이력이 맞다는 가정이다. 그 이력이 틀렸다면 이 쿼리로는 못 잡는다. 같은 결제 키로 연장이 정상적으로 두 번 일어난 경우, 예를 들어 업그레이드도 여기에 걸린다. 그래서 change_type과 금액을 같이 보고 제외 대상을 손으로 확인한다.
실행 전 확인 순서는 이렇다.
- 보정 대상 구독 행과 변경 이력을 백업 테이블로 따로 떠둔다.
- 탐지 쿼리와 fix_target의 건수를 적어두고, PG사 이벤트 로그와 대조한다.
- 트랜잭션 범위를 BEGIN부터 COMMIT까지로 확인한다. 그 밖에서 실행하지 않는다.
- 정상적인 반복 연장을 제외했는지 확인한다.
- 보정 대상 고객에게 어떤 안내를 할지 정한다. 만료일이 바뀌면 고객 화면도 바뀐다.
- 잔액이나 환불이 걸린 건은 자동 보정하지 않는다. 사람이 하나씩 판단한다.

중복 방지를 넣어도 놓치는 경우와 로그로 잡는 법
이 방법으로도 막히지 않는 경우가 있다. 내가 생각하는 대표 경우는 네 가지다.
- 기록 INSERT 전에 프로세스가 죽는 경우. 200을 아직 안 보냈다면 PG사가 재전송하니 정상 흐름이다. 문제는 응답을 먼저 보낸 경우다. 1단계 순서를 지켜야 한다.
- 이벤트 ID가 없거나 재전송마다 바뀌는 PG. 대체 키의 방어는 불완전하다. 이 경우 막는 건 (b)의 비즈니스 가드와 탐지 쿼리뿐이다. 완벽하지 않다는 걸 인정하고 쓴다.
- 동시에 도착한 두 웹훅이 서로 다른 event_key로 같은 결제를 가리키는 경우. 2(a)는 event_key 단위라 여기서는 못 막는다. 보완하려면 결제 키 기준으로 구독 행을 FOR UPDATE로 잠그는 방법이 있다. 나는 아직 이 잠금을 넣지 않았다.
- 취소된 결제에 승인이 늦게 도착하는 경우. event_type과 현재 상태를 비교해서 역행하는 전이는 무시하도록 조건을 건다.
운영에서는 로그를 이 순서로 본다.
- 장기 대기 건 확인: 처리가 멈춘 건이 있는지 본다.
SELECT event_key, event_type, status, received_at, locked_at FROM payment_webhook_event WHERE status IN ('received', 'processing') AND received_at < now() - make_interval(secs => $1) ORDER BY received_at; - 실패 건 확인: 최근 실패의 원인을 본다.
SELECT event_key, event_type, attempt_count, last_error FROM payment_webhook_event WHERE status = 'failed' ORDER BY received_at DESC LIMIT $1; - 판별 기준: last_error에 “duplicate key value violates unique constraint”가 찍혀 있으면 중복 차단이 제대로 된 것이다. 장애가 아니다. 이 문구가 비즈니스 로직 에러와 섞여 있으면 INSERT 경로에서 ON CONFLICT를 빠뜨렸는지 확인한다.
- 중복 반영 확인: 위의 탐지 쿼리를 하루 한 번 돌린다. 결과가 생기면 앞의 정리 절차로 넘긴다.
- 알람 조건: failed 건이 남아 있거나 장기 대기 건이 생기면 알림을 보낸다. 임계치는 트래픽을 보고 정한다. 아직 여기에 맞는 숫자를 정하지 못했다.
요약하고 오늘 할 일 정하기
| 단계 | 할 일 | 확인 방법 |
|---|---|---|
| 1단계 기록 | 이벤트 키 확정, 유니크 제약, 기록 커밋 후 200 | 같은 이벤트를 두 번 보냈을 때 영향 행이 0인지 |
| 2단계 처리 | 처리 권한 잡기, 트랜잭션, 비즈니스 가드 | 같은 event_key를 두 번 처리해도 반영이 한 번인지 |
| 3단계 재처리 | failed와 장기 대기 건을 워커가 다시 집기 | failed 건이 done으로 바뀌는지 |
오늘은 이벤트 ID가 재전송에도 유지되는지부터 PG사 문서에서 확인한다. 이번 주에는 처리 테이블과 가드를 스테이징에 넣고, 같은 이벤트를 일부러 두 번 보내 본다. 배포 후에는 탐지 쿼리와 failed 건 조회를 며칠 동안 매일 돌린다.
아직 못 푼 것은 두 가지다. 하나는 이벤트 ID가 없는 PG의 재전송 키가 실제로 안정적인지 테스트하지 않았다는 것이다. 다른 하나는 동시 레이스를 결제 키 잠금으로 막을지 정하지 못했다는 것이다. 다음 글에서 이 둘을 다룰 계획이다. 내가 만든 다른 서비스와 작업은 wallenstein.dev에 정리해 두었다.
1인 빌더 아일리고가 씁니다. 잘된 것도 망한 것도 적습니다. 영상은 제가 만든 ClipSquare 에서 나옵니다.
궁금해할 만한 것들
웹훅이 같은 결제 알림을 두 번 보내는 이유는 뭔가요?
PG사는 우리 서버가 성공 응답을 제때 주지 않으면 실패로 보고 같은 이벤트를 다시 보냅니다. 핸들러 안에서 외부 API 호출이 끝날 때까지 응답을 미루면 타임아웃이 먼저 나기 쉽습니다. 그래서 중복이 생기면 PG사를 탓하기 전에 우리 응답 시간부터 확인하는 게 맞습니다.
중복 수신을 막을 고유 키는 무엇으로 잡아야 하나요?
1순위는 PG사가 주는 이벤트 ID입니다. 재전송에도 같은 값이 오는지는 PG사 문서와 실제 재전송으로 확인해야 합니다. 이벤트 ID가 없다면 결제 키, 이벤트 타입, 상태를 묶은 값을 대체 키로 씁니다.
주문 번호 하나로 중복을 막으면 안 되나요?
안 됩니다. 같은 주문에 부분 취소가 붙으면 취소 알림이 승인 알림과 같은 키로 보여서 버려집니다. 그러면 취소가 반영되지 않은 채 주문이 완료 상태로 남습니다.
처리 기록 테이블에 처리 완료 여부 boolean 하나만 두면 안 되나요?
처음엔 충분해 보이는데, 처리 중과 실패가 모두 false로 보여서 재처리해야 할지 판단이 안 됩니다. 저는 상태값(received, processing, done, failed)과 시도 횟수를 같이 둡니다. 그래야 재전송인지 진짜 실패인지 구분할 수 있습니다.
중복 키로 막으면 순서 역전 문제도 해결되나요?
해결되지 않습니다. 취소 알림이 승인보다 먼저 도착하면, 나중에 처리된 승인이 취소된 결제를 다시 완료 상태로 돌려놓을 수 있습니다. 중복 검사와 별도로 상태 전이가 허용되는 순서인지 검사해야 합니다.
중복 처리를 막은 뒤에는 무엇부터 확인하면 되나요?
돈과 권한에 닿는 항목부터 봅니다. 구독 만료일, 잔액, 결제 완료 여부를 결제 내역과 대조하고, 알림 메일이나 로그 문구 중복은 나중에 고쳐도 됩니다. 이미 두 번 반영된 건은 자동 보정 전에 한 건씩 수동으로 확인하는 편이 안전합니다.
