Skip to main content
웹훅이란 스텝페이에서 발생하는 정보를 실시간으로 알려주는 기능입니다. 다양한 스텝페이 이벤트를 제공하고 있으며 원하는 이벤트만 연동하여 수신받으실 수 있습니다.

​
웹훅 사용 하기

아래의 순서대로 웹훅 연동을 위한 준비하실 수 있습니다. 그리고 이벤트 유형에 맞는 액션이 발생하면 웹훅이 전송됩니다. 상세 페이지에서 전송 내역을 확인하실 수 있습니다.

​
STEP 1

  • 웹훅을 수신 받을 end-point를 준비합니다. 수신받으실 데이터는 API Spec를 참조해주세요.

​
STEP 2

​
STEP 3

  • 등록한 이벤트를 받아볼 수 있는 액션을 합니다. (예. ‘청구서 생성’ 이벤트를 연동했을 경우, 청구서를 생성한다.)

​
STEP 4

  • 웹훅 상세보기 페이지에서 전송 내역을 확인합니다. 웹훅 상세

​
주의사항

웹훅 이벤트를 전송하는 순서는 보장되지 않습니다. 웹훅 이벤트는 실시간으로 발생하며, 이를 통해 사용자에게 빠른 업데이트를 제공하려고 노력합니다. 그러나 네트워크 지연, 서버 처리 시간 등의 이유로 인해, 이벤트의 전송 순서가 원래의 발생 순서와 일치하지 않을 수 있습니다. 이는 웹훅 구조의 특성상 피할 수 없는 문제로, 이벤트를 수신하는 시스템이 이벤트의 순서를 가정하고 동작하도록 설계되어 있다면 문제가 발생할 수 있습니다. 이러한 이유로, 웹훅 이벤트를 처리하는 로직은 반드시 이벤트가 순서대로 전달되지 않을 수 있다는 것을 고려하여 설계되어야 합니다. 이벤트 순서에 의존하는 처리를 최소화하고, 가능한 각 이벤트를 독립적으로 처리할 수 있도록 하는 것이 좋습니다. 이 점을 유념하시어 웹훅을 사용하실 때 발생할 수 있는 문제에 대비하시기 바랍니다.

​
웹훅 연동하기

웹훅 연동에 필요한 정보입니다. 전달하는 Spec은 기본적으로 동일하며, Spec 내의 data 프로퍼티가 이벤트별로 가변적입니다. 스텝페이가 제공하는 이벤트를 확인하시고 이벤트에 맞는 스키마를 대응해서 데이터를 수신받으실 수 있습니다.

​
API Spec

웹훅으로 부터 받을 수 있는 API Spec입니다. 현재 지원하는 Content-Type은 ‘application/json’만 가능합니다.

​
✔️ Webhook Request

아래는 webhook request 정보를 설명하는 표입니다. 모든 웹훅 요청은 아래의 규격으로 전송되며, event(이벤트 타입) 으로 이벤트를 구분할 수 있습니다.
변수명타입description
timestampLongtimestamp
versionStringAPI Version
eventString이벤트 타입
dataObjectSchema
  • JSON Example
{
  "timestamp": 1688697915,
  "version": "v1",
  "event": "subscription.usage.added",
  "data": {...} // version과 매칭되는 Schema
}

​
웹훅 테스트

​
수신 데이터 확인하기

연동 전에 수신되는 데이터만 확인해보고 싶은 경우에 다음의 방법으로 데이터를 확인해볼 수 있습니다.

​
STEP 1

​
STEP 2

  • 페이지의 Your unique URL 를 복사합니다. 웹훅 사이트1

​
STEP 3

  • 포탈에 해당 URL로 이벤트를 등록합니다. 웹훅 사이트1

​
STEP 4

  • 이벤트에 해당하는 액션을 취합니다. 예시의 경우 ‘결제완료(payment.completed)’ 액션을 수행합니다.

​
STEP 5

  • https://webhook.site 에서 수신받은 데이터를 확인합니다. 예시는 ‘결제완료(payment.completed)’이벤트를 수신받은 결과 입니다. 웹훅 사이트2