---
title: 웹훅(Webhook)이 무엇인가요?
category: 자주 묻는 질문 (일반 문의) > 일반 문의 > 자주 묻는 질문
tags:
  - 공통
pgCompanies:
  - null
searchTags:
  - webhook
  - 웹훅
datetime: 2024-05-29T15:00:00.000Z
---

## 웹훅(Webhook)이란?

특정 이벤트가 발생하였을 때 타 서비스나 응용프로그램으로 알림을 보내는 기능입니다.

- Webhook 프로바이더는 해당 이벤트가 발행하면 HTTP POST 요청을 생성하여 callback URL(endpoint)로 이벤트 정보을 보냅니다.
- 주기적으로 데이터를 폴링(polling)하지 않고 원하는 이벤트에 대한 정보만 수신할 수 있어서 webhook은 리소스나 통신측면에서 훨씬 더 효율적입니다.
- Webhook을 활용하면 커스텀 기능이나 다른 애플리케이션과 연동하여 기능을 확장할 수 있습니다.
- 포트원에서는 결제 완료 등 이벤트가 발생했을 때 고객사의 서버에 전송하고 있습니다.
- 이벤트가 발생하면 포트원 콘솔에 등록된 웹훅 URL로 HTTP POST 요청을 보냅니다.\
  고객사에서는 이 요청을 받아 최신 결제 정보로 동기화 하도록 구현해야 합니다.

## 웹훅 연동이 꼭 필요한가요?

안정적인 결제 처리를 위해 웹훅 연동을 강력히 권장합니다. \
인터넷 연결 끊김, 브라우저 자동 새로고침 등의 이유로 클라이언트에서 결제 완료에 대한 응답을 받지 못하는 경우가 간헐적으로 발생합니다. 이런 경우 연동한 웹훅을 통해 누락 없이 결제 정보를 동기화할 수 있습니다.

## 웹훅 발생 이벤트

포트원 웹훅은 다음과 같은 이벤트에 발생됩니다.

- 결제가 승인되었을 때(모든 결제 수단) - (status : paid)
- 가상계좌가 발급되었을 때 - (status : ready)
- 가상계좌에 결제 금액이 입금되었을 때 - (status : paid)
- 예약결제가 시도되었을 때 - (status : paid or failed)
- 관리자 콘솔에서 결제 취소되었을 때 - (status : cancelled)

<Callout icon="⚠" title="결제 실패 시에는 웹훅이 호출되지 않아요!" content="" />

## 웹훅 URL 설정

웹훅 URL을 설정하면 포트원에서 이벤트 발생 시 해당 URL로 웹훅을 전송합니다. URL은 관리자 콘솔에서 두 가지 형태로 지원하고 있습니다. 콘솔에서 설정했더라도 결제 시에 notice\_url파라미터로 지정하여 호출하는 경우 해당 URL로 전송됩니다.

<Callout title="V2 웹훅 URL 설정 방법 보러가기↗" />

<Callout title="V1 웹훅 URL 설정 방법 보러가기↗" />

## 웹훅 재 전송이 가능한가요?

웹훅은 기본적으로 1회 전송되도록 설정되어 있습니다. \
네트워크 에러가 발생하거나 고객사 응답(HTTP 상태 코드)이 500번대인 경우, 재발송 설정을 원하신다면 웹훅이 최대 5회까지 1분 간격으로 재시도될 수 있습니다.

<Callout title="웹훅 재발송 방법 보러가기 ↗" />
