콘텐츠로 이동

웹훅 개요

웹훅은 out-of-band 로 발생하는 이벤트(가장 중요하게는 결제의 온체인 컨펌)에 서버가 반응할 수 있게 해줍니다. 주문 처리(fulfillment)의 신뢰 가능한 시그널은 웹훅입니다.

동작 방식

POST /v1/webhook_endpoints 로 엔드포인트 URL 과 수신할 이벤트를 등록합니다.
ParaSta 가 서명용 secret 을 반환합니다. 반드시 저장하세요 — 이후 다시 조회할 수 없습니다.
이벤트 발생 시 ParaSta 가 X-ParaSta-Signature 헤더와 함께 JSON 페이로드를 등록한 URL 로 POST 합니다.
서명을 검증하고, event.id 로 멱등성을 체크한 뒤 처리합니다.

페이로드 형태

{
  "id": "evt_abc123",
  "type": "checkout.session.completed",
  "created": "2026-05-06T10:32:01Z",
  "data": {
    "object": { /* 관련 객체 — Checkout Session, Payment 등 */ }
  },
  "livemode": false
}

모범 사례

10초 이내에 2xx 응답. 2xx 가 아니면 ParaSta 가 재시도합니다.
멱등성 보장. 동일 이벤트가 여러 번 전달될 수 있으므로 event.id 로 중복 제거하세요.
순서가 어긋날 수 있음. 특히 payment.pending 과 payment.succeeded — 어떤 순서로도 받을 수 있게 상태 머신을 설계하세요.

함께 보기