[TIL]20240829 웹훅(Webhook)

결제 기능을 구현하면서 웹훅(Webhook)이라는게 꼭 붙어있어서 내가 해야하는 부분인 줄 알고 공부해야하나? 라는 생각을 갖고있었다. 특히 포트원(PortOne)과 같은 결제 대행 서비스를 사용하면서 웹훅이 어떤 역할을 하는지 이해하는 게 필요하다고 생각했고, 매니저님이 프론트영역이라고는 하셨지만, 웹훅이라는 이름이 맘에들었기 때문에🤣 내용을 정리하기로 했다! 

😚웹훅(Webhook)?

웹훅(Webhook)은 서버에서 특정 이벤트가 발생할 때 다른 서버의 특정 엔드포인트(URL)로 HTTP 요청을 보내는 방식의 비동기적 통신 방법이다. 쉽게 말해, 웹훅은 이벤트 기반으로 동작하며, 서버 간의 데이터를 실시간으로 전달하는 데 매우 유용하다. 웹훅을 이용하면 서버가 특정 이벤트(예: 결제 완료, 주문 상태 변경 등)를 자동으로 감지하고 후속 작업을 처리할 수 있다.

 

▶ 웹훅의 역할

웹훅은 다음과 같은 상황에서 중요한 역할을 한다.

 

→ 이벤트 알림:

서버에서 발생한 특정 이벤트(예: 결제 완료, 취소, 실패 등)를 다른 서버나 시스템에 알린다.

→ 데이터 동기화:

여러 시스템 간 데이터를 실시간으로 동기화하는 데 사용된다. 예를 들어, 결제 시스템과 백엔드 서버 간의 결제 결과를 동기화할 수 있다.

→ 자동화:

결제 성공 시 자동으로 주문 상태를 업데이트하거나, 결제 실패 시 사용자에게 알림을 보내는 등 후속 작업을 자동화할 수 있다.

 

▶ 웹훅과 결제 기능의 관계

포트원(PortOne)과 같은 결제 대행 서비스를 사용하면 결제 결과를 서버에 전달할 수 있는 방법이 필요하다. 이때 웹훅은 매우 중요한 역할을 한다. 사용자가 결제를 완료하면 포트원 서버는 사전에 설정된 웹훅 URL로 결제 결과를 HTTP POST 요청을 통해 전달한다. 백엔드 서버는 이 요청을 받아 결제 상태를 검증하고 후속 작업을 수행한다. 이러한 방식으로 웹훅을 사용하면 결제와 같은 중요한 정보를 클라이언트가 폴링(polling) 방식으로 요청하지 않고도 서버 간에 직접적으로 전달할 수 있다.

 

▷ 폴링(polling) 방식? 

→ 폴링(Polling)은 클라이언트가 일정한 간격으로 서버에 요청을 보내서 새로운 데이터나 상태 변화를 확인하는 방식이다. 구현이 단순하지만, 실시간성에 한계가 있고 불필요한 요청이 많아 네트워크 자원 소모가 크다는 단점이 있다.

 

 

▶웹훅을 알아야 하는 이유

웹훅은 프론트엔드의 영역이라고 생각할 수 있지만, 백엔드 개발자에게도 매우 중요한 개념이다. 

 

→ 서버 간 통신 처리:

웹훅은 서버 간 통신의 일환이다. 백엔드 개발자는 외부 시스템(예: 결제 대행사)과의 통신을 처리하기 위해 웹훅 엔드포인트를 구현해야 한다. 결제와 같은 이벤트가 발생할 때 외부 서버에서 백엔드 서버로 데이터를 전달하는 역할을 하기 때문이다.

→ 데이터 검증 및 처리:

웹훅을 통해 수신된 데이터는 자동으로 처리되지만, 그 과정에서 데이터의 무결성과 보안을 검증하는 작업이 필수적이다. 백엔드 개발자는 웹훅을 통해 전달된 결제 결과를 검증하고, DB에 저장하거나 후속 작업을 처리하는 로직을 작성해야 한다.

→ 비즈니스 로직 관리:

웹훅이 수신하는 이벤트는 결제 완료, 취소, 실패 등 다양하다. 이러한 이벤트를 처리하는 로직은 백엔드에서 작성된다. 예를 들어, 결제가 성공하면 주문 상태를 '결제 완료'로 업데이트하고, 실패 시 '결제 실패'로 변경하는 등 백엔드의 비즈니스 로직을 관리해야 한다.

→ 에러 처리와 로깅:

외부 시스템과의 통신에서 발생할 수 있는 오류를 처리하고, 필요시 재시도 로직을 구현해야 한다. 웹훅 요청이 제대로 수신되지 않거나 처리 중 에러가 발생하는 경우를 대비해 에러 로깅과 복구 절차를 마련해야 한다.

 

▶ 웹훅 엔드포인트 구현 예시

→ PaymentController에 웹훅 엔드포인트를 추가한 코드 예시이다. 이 엔드포인트는 포트원에서 결제 결과를 수신하고 처리하는 역할을 한다. (기본 다른 API들은 생략)

package com.clean.cleanroom.payment.controller;

import com.clean.cleanroom.payment.dto.*;
import com.clean.cleanroom.payment.service.PaymentService;
import com.clean.cleanroom.payment.service.PortOneService;
import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/payments")
@CrossOrigin(origins = "*")
public class PaymentController {

    private final PaymentService paymentService;
    private final PortOneService portOneService;

    public PaymentController(PaymentService paymentService, PortOneService portOneService) {
        this.paymentService = paymentService;
        this.portOneService = portOneService;
    }

    // 기존 API 생략...

    /**
     * 결제 결과를 처리하는 웹훅 엔드포인트
     * PortOne에서 결제 결과를 수신하고 처리하는 엔드포인트입니다.
     *
     * @param webhookRequestDto PortOne에서 전송한 웹훅 요청 데이터
     * @return String 처리 결과 메시지
     */
    @PostMapping("/webhook")
    public ResponseEntity<String> handlePaymentWebhook(@RequestBody WebhookRequestDto webhookRequestDto) {
        boolean isSuccess = paymentService.processPaymentResult(webhookRequestDto);

        if (isSuccess) {
            return ResponseEntity.ok("웹훅이 성공적으로 처리되었습니다.");
        } else {
            return ResponseEntity.status(400).body("웹훅 처리에 실패하였습니다.");
        }
    }
}

→ 웹훅 엔드포인트 정의: /api/payments/webhook 경로로 웹훅 요청을 받는다.

→ 데이터 처리: WebhookRequestDto를 통해 포트원에서 전송한 결제 결과 데이터를 수신한다.

→ 결과 응답: 처리 결과에 따라 성공 또는 실패 메시지를 반환한다.

 

▶ 백엔드 개발자가 알아야 할 웹훅의 핵심 포인트

 

→ 인증 및 보안:

웹훅 요청은 외부 서버에서 전송되기 때문에, 백엔드 개발자는 요청의 진위 여부를 확인하기 위한 보안 로직을 구현해야 한다. 예를 들어, 포트원에서 발송된 요청이 맞는지 검증하는 작업이 필요하다.

→ 재시도 로직:

결제 결과를 받아 후속 작업을 진행할 때, 예기치 못한 오류가 발생할 수 있다. 이럴 경우 웹훅 요청을 재시도하는 로직이 필요하다.

→ 데이터 일관성 유지:

결제 처리와 같은 중요한 작업에서는 데이터 일관성을 유지하는 것이 매우 중요하다. 웹훅을 통해 수신된 데이터가 올바르게 처리되었는지 확인해야 한다.

 

▶알림기능이 많은데 왜 꼭 웹훅이야...? 

웹훅(Webhook)은 SSE(Server-Sent Events)나 웹소켓(WebSocket)과 같은 실시간 통신 기술과 비교했을 때 결제 기능에 더 적합한 이유가 있다. 결제와 같은 민감한 데이터 전송에서는 신뢰성과 보안이 가장 중요하기 때문이다. 결제 시스템은 사용자 경험과 데이터의 무결성을 보장하기 위해 매우 신중하게 설계되어야 한다. 아래의 이유들로 인해 결제 기능에서는 웹훅을 사용하는 것이 더 적합하다.

 

→ 보안(Security):

SSE나 웹소켓은 클라이언트와 서버 간의 실시간 연결을 유지하는 방식이기 때문에 연결이 지속적으로 열려 있어야 한다. 하지만 이러한 방식은 클라이언트와 서버 간의 지속적인 연결로 인해 보안적인 위험을 초래할 수 있다.

반면, 웹훅은 서버 간의 통신으로, 결제 데이터와 같은 민감한 정보를 신뢰할 수 있는 서버 간의 보안된 통신을 통해 전송한다. 이는 데이터의 무결성과 보안을 보장하는 데 유리하다.

→ 신뢰성(Reliability):

SSE나 웹소켓은 클라이언트의 네트워크 상태에 따라 연결이 끊길 수 있는 가능성이 있다. 만약 네트워크 상태가 불안정하다면, 중요한 결제 정보를 놓치거나 전송 오류가 발생할 수 있다.

웹훅은 이벤트가 발생할 때마다 서버 간 HTTP 요청을 보내는 방식이기 때문에 네트워크 상태의 영향을 덜 받으며, 신뢰성 있게 결제 결과를 전달할 수 있다.

→ 비동기성(Asynchronous Processing):

결제 기능은 즉각적으로 처리되기보다는 비동기적으로 처리되는 경우가 많다. 예를 들어, 결제 대행사가 결제 요청을 처리하는 동안 지연이 발생할 수 있으며, 그 결과를 클라이언트가 계속 대기하면서 처리하기에는 적합하지 않다.

웹훅은 서버 간의 비동기적 이벤트 기반 처리를 지원하기 때문에 결제 대행사에서 결제가 완료되었을 때 서버가 이를 비동기적으로 받아서 후속 작업을 처리할 수 있다.

→ 리소스 효율성(Resource Efficiency):

SSE나 웹소켓은 클라이언트와 서버 간의 연결을 계속 유지하기 때문에 서버 리소스를 소모한다. 결제와 같은 특정 이벤트에 대한 알림을 수신하기 위해 계속 연결을 유지하는 것은 비효율적이다.

웹훅은 특정 이벤트가 발생했을 때만 서버 간 요청을 보내기 때문에 리소스 효율성이 더 높다. 따라서 대규모 트래픽을 처리하는 결제 시스템에서는 웹훅을 사용하여 서버 리소스를 효율적으로 관리할 수 있다.

→ 적합성(Fit for Purpose):

SSE와 웹소켓은 실시간 채팅, 주식 시세, 게임 알림 등 지속적으로 데이터를 주고받아야 하는 용도로 적합하다. 반면, 결제 기능은 특정 이벤트(결제 성공, 실패, 취소 등) 발생 시에만 데이터를 전송하면 되므로, 이러한 이벤트 기반 처리 방식에는 웹훅이 더 적합하다.

 

▶ 결제 시스템에서 웹훅을 사용하는 이유

웹훅은 결제 시스템에서 실시간으로 결제 상태를 확인하고 처리 결과를 받아야 하는 상황에서 효과적이다. 결제 대행사가 결제 완료 후 서버에 결제 상태를 알려주기 위해 사용하는 웹훅 방식은 결제 데이터의 정확성과 보안을 유지할 수 있게 해준다. 또한, 이러한 방식은 백엔드 서버가 클라이언트와의 연결을 유지하지 않고도 결제 결과를 처리할 수 있어 비즈니스 로직을 더 안정적으로 관리할 수 있게 한다.

 

▶정리

웹훅은 실시간 데이터 전송을 통해 결제 결과를 안전하고 신뢰성 있게 전달하는 데 중요한 역할을 한다. 백엔드 개발자는 웹훅을 통해 결제 처리와 같은 중요한 이벤트를 효과적으로 관리하고 처리할 수 있어야 한다. 그냥 웹훅이란걸 대충 봤을때는 알림 기능같은데 왜 꼭 웹훅을 써야하는건지 궁금했다. SSE나 웹소켓과 같은 실시간 통신 방법과의 비교를 통해서 웹훅이 결제 시스템에서 보안성, 신뢰성, 비동기성, 리소스 효율성 측면에서 더 적합한 이유를 알게 되고나서 이것도 결제시스템 설계 일부구나 싶다..!