3년 전, 나의 웹훅 테스트는 ngrok, sleep(5) 호출, 그리고 행운을 비는 마음이 전부였습니다. 현재의 패턴은 그 중 어느 것도 사용하지 않습니다.

만약 당신이 웹훅 연동을 테스트해 본 적이 있다면, 이 상황이 아마 익숙하게 들릴 것입니다.

로컬 애플리케이션을 시작합니다.

ngrok을 실행합니다.

임시 URL을 제3자 애플리케이션(third-party application)에 복사합니다.

이벤트를 트리거합니다.

몇 초를 기다립니다.

웹훅이 도착하기를 바랍니다.

도착하지 않으면 또 다른 sleep(5)를 추가합니다.

테스트를 다시 실행합니다.

결국, 작동합니다.

URL이 바뀔 때까지는 말이죠.

혹은 네트워크에 문제가 생기거나.

또는 당신의 CI 파이프라인이 ngrok에 접근할 수 없거나 말입니다.

웹훅 테스트는 항상 약간 어색했습니다. 왜냐하면 두 개의 독립적인 시스템 사이에서 발생하는 비동기적 대화(asynchronous conversation)를 검증해야 하기 때문입니다. 클라이언트가 요청과 응답을 모두 제어하는 전통적인 API 요청과 달리, 웹훅은 당신의 애플리케이션이 서버가 되어야 합니다.

결제 게이트웨이(payment gateways), CRM, 메시징 플랫폼, 그리고 SaaS 애플리케이션을 위한 웹훅 연동을 구축하고 테스트한 끝에, 나는 단순하고 결정론적(deterministic)이며, 개발자의 노트북뿐만 아니라 CI에서도 똑같이 잘 작동하는 패턴을 정착시켰습니다.

이 패턴은 하나의 아이디어를 중심으로 합니다:

웹훅을 직접 테스트하지 마세요. 당신의 웹훅 수신부(webhook receiver)를 테스트하세요.

여기 내가 계속해서 돌아오게 되는 패턴이 있습니다.

"인박스(Inbox)" 패턴 — 큐(Queue)를 가진 작은 HTTP 수신부

대부분의 웹훅 테스트는 모든 것을 한 번에 검증하려고 시도합니다.

웹훅이 전송됩니다.

당신의 애플리케이션이 이를 수신합니다.

비즈니스 로직이 실행됩니다.

데이터베이스가 업데이트됩니다.

알림이 트리거됩니다.

로그가 기록됩니다.

무언가 실패했을 때, 문제가 실제로 어디에서 발생했는지 알기가 어렵습니다.

대신, 수신(reception)과 처리(processing)를 분리하세요.

당신의 웹훅 수신부가 오직 세 가지만 수행한다고 상상해 보세요:

1. HTTP 요청을 수락합니다.
2. 이를 검증(validate)합니다.
3. 이를 인박스 큐(inbox queue)에 넣습니다.

그게 전부입니다.

처리는 나중에 이루어집니다.

당신의 수신부는 매우 작아집니다.

Webhook Sender
        │
        ▼
...

이제 모든 단계를 독립적으로 테스트할 수 있습니다.

이 패턴이 작동하는 이유

인박스는 임시 우편함 역할을 합니다.

당신의 웹훅 엔드포인트(webhook endpoint)는 오직 한 가지 질문에만 답합니다:

"유효한 웹훅을 수신했는가?"

그 이후의 모든 사항은 별도의 테스트 세트에 속합니다.

이점은 다음과 같습니다:

• 더 빠른 실행
• 더 쉬운 디버깅 (debugging)
• 더 나은 재시도 처리 (retry handling)
• 더 명확한 관심사 분리 (separation of concerns)

전체 워크플로 (workflow)가 완료되기를 기다리는 대신, 테스트는 단순히 다음 사항들을 검증합니다:

• HTTP 200 반환 여부
• 페이로드 (payload) 저장 여부
• 메타데이터 (metadata) 캡처 여부
• 큐 (queue) 엔트리 생성 여부

비즈니스 로직 (business logic)은 별도로 검증될 수 있습니다.

더 나은 멘탈 모델 (Mental Model)

웹훅 엔드포인트를 이메일 수신함과 같다고 생각하세요.

이메일을 받는 것과 그것을 처리하는 것은 동일하지 않습니다.

수신함이 안정적으로 작동한다면, 다운스트림 (downstream) 프로세싱을 추론하기가 훨씬 쉬워집니다.

서명 검증 (Signature Verification): 통합 버그의 80%를 잡아내는 테스트

대부분의 웹훅 제공업체는 모든 요청에 서명(sign)을 합니다.

예시:

• Stripe
• GitHub
• Shopify
• Slack
• Twilio

송신자는 암호화 서명 (cryptographic signature)을 계산합니다.

수신자는 페이로드를 신뢰하기 전에 이를 검증합니다.

하지만 이것은 가장 빈번하게 누락되는 테스트 중 하나입니다.

서명 검증이 중요한 이유

다음과 같은 요청을 상상해 보세요:

POST /webhook

헤더 (Headers):

X-Signature:
a9f72d...

페이로드 (Payload):

{
  "event": "payment.completed"
}

서명 검증이 잘못되면 다음 두 가지 중 하나가 발생합니다:

1. 정당한 웹훅이 거부됩니다.
2. 가짜 웹훅이 수락됩니다.

두 결과 모두 바람직하지 않습니다.

모든 테스트 스위트 (test suite)에 필요한 세 가지 서명 테스트

해피 패스 (happy path)만 테스트하는 대신, 다음을 포함하세요:

유효한 서명 (Valid Signature)

예상 결과:

200 OK

웹훅 수락됨.

수정된 페이로드 (Modified Payload)

서명을 계산한 후 문자 하나를 변경합니다.

예상 결과:

401 Unauthorized

페이로드 검증에 실패해야 합니다.

잘못된 비밀키 (Wrong Secret)

잘못된 비밀키 (secret)를 사용하여 서명을 생성합니다.

예상 결과:

401 Unauthorized

이 단 하나의 테스트만으로도 프로덕션 (production)에 배포하기 전 엄청난 수의 설정 실수를 잡아낼 수 있습니다.

제 경험상, 구현 과정에서 발견되는 웹훅 (webhook) 통합 문제의 대부분은 서명 검증 (signature verification)에서 발생합니다.

재시도 동작 (Retry Behavior): 30분을 기다리지 않고 테스트하는 방법

많은 웹훅 제공업체는 전달에 실패할 경우 재시도를 수행합니다.

때로는 즉시 재시도합니다.

때로는 몇 분 후에 재시도합니다.

때로는 지수 백오프 (exponential backoff)를 사용하여 재시도합니다.

실제 재시도 간격을 기다리는 것은 자동화된 테스트를 고통스러울 정도로 느리게 만듭니다.

다행히도, 그럴 필요는 없습니다.

시계 조작하기 (Fake the Clock)

시간 자체에 의존하는 대신, 재시도 스케줄링을 주입 가능하게 (injectable) 만드세요.

예를 들어:

재시도 정책 (Retry Policy)

시도 1
...

프로덕션 (production) 환경에서는:

5분
15분
30분

테스트 환경에서는:

10ms
20ms
40ms

로직은 정확히 동일합니다.

타이밍만 다를 뿐입니다.

무엇을 테스트해야 하는가?

훌륭한 재시도 테스트 스위트 (retry suite)는 다음 사항을 검증합니다:

• 전달 실패 시 다음 시도를 예약하는가.
• 전달 성공 시 향후 재시도를 중단하는가.
• 최대 재시도 횟수를 준수하는가.
• 중복된 재시도가 중복된 비즈니스 이벤트를 생성하지 않는가.

이 모든 항목은 수백 밀리초 (milliseconds) 내에 실행될 수 있습니다.

기다릴 필요가 없습니다.

일시적인 실패 시뮬레이션하기

네트워크를 끊는 대신, 단순히 다음을 반환하세요:

HTTP 500

두 번 수행합니다.

그다음:

HTTP 200

세 번째 요청에서 반환합니다.

다음 사항을 검증하세요:

• 세 번의 시도가 발생했는가.
• 최종 처리가 한 번 이루어졌는가.
• 큐 (queue)에 완료된 이벤트가 하나 포함되어 있는가.

결정론적 (Deterministic)이고,

빠르며,

신뢰할 수 있습니다.

순서가 맞지 않는 전달 (Out-of-Order Delivery) — 대부분의 테스트 스위트가 건너뛰는 테스트

많은 엔지니어가 프로덕션에 배포하기 전까지 발견하지 못하는 사실이 있습니다:

웹훅 전달 순서는 보장되지 않습니다.

두 개의 이벤트가 있다고 가정해 봅시다.

주문 업데이트 (Order Updated)

가 다음보다 먼저 도착합니다:

주문 생성 (Order Created)

이는 완전히 허용되는 상황입니다.

많은 제공업체는 순서를 가정해서는 안 된다고 명시적으로 문서화하고 있습니다.

그럼에도 불구하고 수많은 애플리케이션이 실수로 시간 순서에 따른 전달에 의존합니다.

간단한 예시

예상되는 순서:

고객 생성 (Create Customer)
↓

...

실제 전달 순서:

구독 활성화 (Activate Subscription)
↓

...

만약 당신의 시스템이 순서를 가정한다면, 두 번째 이벤트는 실패하게 됩니다.

운영 환경(Production)이 불일치하게 됩니다.

테스트 방법

이벤트를 시간 순서대로 다시 재생(Replaying)하는 대신, 다음과 같이 시도해 보세요:

Event 1이 전달되기 전에:

Event 2

을 전송합니다.

다음 사항을 관찰하세요:

• 처리가 재시도(Retry)되는가?
• 이벤트가 지연(Delayed)되는가?
• 애플리케이션이 자동으로 복구(Recover)되는가?

만약 그렇지 않다면, 중요한 회복 탄력성(Resilience) 격차를 발견한 것입니다.

멱등성(Idempotency) 또한 중요합니다

순서가 뒤바뀐 전달(Out-of-order delivery)은 중복 전달(Duplicate delivery)과 함께 자주 나타납니다.

테스트 스위트(Suite)는 다음 사항을 검증해야 합니다:

Event A
↓

...

이 정확히 하나의 비즈니스 결과(Business outcome)를 생성하는지 확인하십시오.

웹훅(Webhook)은 두 번 도착할 수 있습니다.

하지만 인보이스(Invoice)는 두 번 생성되어서는 안 됩니다.

40줄로 끝내는 웹훅 테스트 템플릿

마지막 패턴은 특정 프로그래밍 언어에 종속되지 않습니다.

거의 모든 웹훅 테스트는 동일한 구조를 따릅니다.

준비 (Arrange)

다음 항목을 생성합니다:

• 테스트 페이로드 (Test payload)
• 서명 (Signature)
• 수신자 (Receiver)
• 인박스 (Inbox)

실행 (Act)

다음 요청을 전송합니다:

POST /webhook

수신 검증 (Assert Reception)

다음 사항을 확인합니다:

• 상태 코드 (Status code)
• 서명 검증 (Signature validation)
• 큐 엔트리 (Queue entry)
• 메타데이터 (Metadata)

처리 검증 (Assert Processing)

인박스(Inbox)를 처리합니다.

다음 사항을 확인합니다:

• 비즈니스 액션 (Business action)
• 데이터베이스 변경 사항 (Database changes)
• 이벤트 완료 (Event completion)

멱등성 검증 (Assert Idempotency)

정확히 동일한 웹훅을 다시 재생(Replay)합니다.

다음 사항을 확인합니다:

• 중복 레코드 없음 (No duplicate records)
• 중복 이메일 없음 (No duplicate emails)
• 중복 인보이스 없음 (No duplicate invoices)

이것이 본질적으로 전체 템플릿입니다.

대부분의 웹훅 통합(Integration)은 페이로드 형태와 서명 알고리즘(Signature algorithm)만 다를 뿐입니다.

테스트 패턴은 거의 동일하게 유지됩니다.

종합하기

성숙한 웹훅 테스트(Webhook testing) 전략은 보통 다섯 가지 계층을 다룹니다:

계층 (Layer)	검증 내용
수신자 (Receiver)	HTTP 엔드포인트가 요청을 수락하는지
...

무엇이 빠져 있는지 확인해 보세요.

다음과 같은 특징이 있습니다:

• 임의의 슬립(Sleep) 호출이 없음.
• 비동기 타이밍(Asynchronous timing)을 기다리지 않음.
• 외부 터널(External tunnels)에 의존하지 않음.
• 수동 검사(Manual inspection)가 없음.

모든 구성 요소가 결정론적(Deterministic)이 됩니다.

모든 실패를 진단하기가 더 쉬워집니다.

모든 테스트가 로컬 실행 및 지속적 통합(Continuous Integration)에 적합해집니다.

마치며

Webhook 통합은 본질적으로 비동기적(asynchronous)이지만, 그렇다고 해서 테스트가 예측 불가능해야 한다는 의미는 아닙니다.

Webhook 수신을 비즈니스 로직 처리와 분리하고, 서명(signatures)을 독립적으로 검증하며, 재시도(retries)를 기다리는 대신 이를 시뮬레이션하고, 순서가 뒤바뀐 전달(out-of-order delivery)을 의도적으로 테스트함으로써, 빠르면서도 탄력적인(resilient) 테스트 스위트(test suite)를 구축할 수 있습니다.

제가 이룬 가장 큰 개선은 프레임워크를 바꾸거나 다른 테스트 도구를 구매한 것이 아니었습니다.

그것은 바로 테스트 자체의 아키텍처(architecture)를 변경한 것이었습니다.

오늘날 동일한 Webhook 테스트가 임시 터널(temporary tunnels), 인위적인 지연(artificial delays), 또는 수동 검증(manual verification)에 의존하지 않고도 로컬, 풀 리퀘스트(pull requests), 그리고 프로덕션 검증 파이프라인(production validation pipelines)에서 실행됩니다.

이것이 바로 자동화된 테스트가 제공해야 하는 신뢰성의 핵심입니다.

만약 **이러한 Webhook 수신을 위해 저희가 배포하는 CI 통합(CI integrations)**을 찾고 계신다면, 다음을 확인해 보세요:

https://totalshiftleft.ai/integrations

Webhook 테스트가 의존하는 가동 요소(moving parts)가 적을수록, 실제 이벤트가 프로덕션에 도착하기 시작할 때 더 큰 확신을 가질 수 있습니다.