Webhook

Webhook은 이벤트 알림을 수신하는 데 사용되는 HTTP 엔드포인트입니다. 특정 이벤트가 발생하면 시스템이 미리 정의된 URL(Webhook URL)로 HTTP 요청을 능동적으로 전송합니다. Webhook은 상태 변경 또는 비동기 작업 결과를 외부 시스템에 알리는 데 일반적으로 사용됩니다.

일반적인 사용 사례

사용 사례	설명
결제 알림	주문 결제가 성공적으로 완료되면 결제 플랫폼이 알림을 전송합니다
인증 업데이트	타사 로그인 서비스가 로그인 상태를 업데이트합니다
비동기 작업 결과	백그라운드 작업이 완료되면 결과를 전송합니다
이벤트 트리거	특정 이벤트가 발생하면 시스템이 외부 서비스에 알립니다

일반 엔드포인트와의 주요 차이점

기술적으로 Webhook은 단순한 HTTP 엔드포인트이지만, 사용 방식에서 차이가 있습니다.

Webhook: 시스템이 외부 URL로 호출을 시작합니다

일반 엔드포인트: 클라이언트가 시스템으로 요청을 전송합니다

Webhook 엔드포인트 생성하기

Apidog 프로젝트에서 왼쪽 사이드바의 "+" 아이콘을 클릭하고 "New Other Protocol APIs" → **"Webhook"**을 선택하십시오.

Webhook을 생성한 후 편집기에서 다음 필드를 입력하십시오.

필드	설명
요청 메서드	일반적으로 `POST`입니다
Webhook 이름	API 문서와 OpenAPI 내보내기에 표시됩니다(예: `order`)
디버그 URL	선택 사항입니다. 테스트 요청을 전송하는 데 사용되는 실제 URL입니다(테스트 전용이며 문서에는 포함되지 않음)
기타 정보	요청 본문, 헤더 및 기타 구성입니다

모든 필수 필드를 완료한 후 **"Save"**를 클릭하십시오.

Webhook 엔드포인트 디버깅하기

Webhook 디버깅은 이벤트 트리거를 시뮬레이션하여 외부 서비스가 요청을 올바르게 수신하는지 확인합니다.

Webhook을 디버깅하려면 다음을 수행하십시오.

Webhook URL을 디버그 URL 필드에 입력하십시오

Webhook 호출을 시뮬레이션하려면 **"Send"**를 클릭하십시오

Webhook 문서

Webhook 문서에는 Webhook 이름, 요청 메서드, 요청 본문과 같은 세부 정보가 포함됩니다. 이를 통해 사용자는 특정 이벤트가 발생했을 때 어떤 종류의 데이터가 전송되는지 더 쉽게 이해할 수 있습니다.

디버그 URL 개인정보 보호

디버그 URL은 문서 또는 OpenAPI 내보내기에 포함되지 않습니다. 이는 내부 테스트 전용입니다.

내보낸 OpenAPI 파일에서 Webhook 엔드포인트는 webhooks 필드 아래에 나열되며, 이는 일반 엔드포인트의 paths 필드와 다릅니다.

FAQ

문서에서 Webhook을 별도로 정의하는 이유는 무엇입니까?

OpenAPI 3.1 사양에 따르면 다음과 같습니다.

일반 엔드포인트는 paths 필드 아래에 정의됩니다

Webhook 엔드포인트는 webhooks 필드 아래에 정의됩니다

이러한 명확한 분리는 다음을 보장합니다.

일반 엔드포인트는 외부 클라이언트가 작업을 수행하거나 데이터를 검색하기 위해 호출합니다

Webhook은 시스템이 외부 서비스에 알리기 위해 트리거합니다

Apidog에서는 이러한 방향성의 차이를 정확하게 반영하고 OpenAPI 내보내기에서 올바른 형식을 보장하기 위해 Webhook을 별도의 엔드포인트 유형으로 취급합니다.

예시:

/orders는 클라이언트가 사용하는 일반 엔드포인트입니다

orderPaid는 주문 결제가 성공적으로 완료되었을 때 시스템에 의해 트리거되는 Webhook입니다

Webhook은 단순한 일반 엔드포인트입니까?

디버그 URL이 API 문서에 표시됩니까?

일반적인 사용 사례#

일반 엔드포인트와의 주요 차이점#

Webhook 엔드포인트 생성하기#

Webhook 엔드포인트 디버깅하기#

Webhook 문서#

FAQ#

일반적인 사용 사례

일반 엔드포인트와의 주요 차이점

Webhook 엔드포인트 생성하기

Webhook 엔드포인트 디버깅하기

Webhook 문서

FAQ