웹훅

웹훅은 결제·환불·구독 이벤트를 내 서버로 받는 방법이에요.
셀러 콘솔에서 수신 URL과 받을 이벤트를 등록하면, 이벤트가 생길 때마다 페이리가 그 URL로 POST를 보내요.
특정 상품에만 적용되도록 범위를 좁힐 수도 있어요.

수신 흐름

수신 서버가 해야 할 일은 세 가지예요.

서명 검증

정말 페이리가 보낸 요청인지 확인해요.

멱등 처리

같은 이벤트가 두 번 와도 한 번만 처리해요.

빠른 200 응답

무거운 작업은 큐로 넘기고 먼저 200을 돌려줘요.

Slack·Notion 같은 외부 서비스로 보낼 때도 그 서비스의 수신 URL을 페이리에 바로 등록하지 마세요.
내 서버를 한 단계 거쳐 서명을 검증한 뒤 전달해야 위조 요청을 막을 수 있어요.

페이리는 HTTP 200만 성공으로 봐요.
201·204를 포함한 그 외 응답·타임아웃·네트워크 오류는 실패로 간주해 재전송해요.
요청 타임아웃은 10초예요.

요청 형태

Standard Webhooks 규격을 따라요.
이벤트 종류는 헤더가 아니라 본문의 type 필드로 와요.


POST /your/webhook HTTP/1.1
Content-Type: application/json
webhook-id: msg_a1b2c3d4-...
webhook-timestamp: 1750000000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj...
 
{ "type": "order.paid", "data": { "id": "ord_3kf9a2", "status": "paid" } }

헤더	설명
`webhook-id`	메시지 고유 ID (`msg_`로 시작). 재전송에도 같은 값이라 멱등 키로 써요
`webhook-timestamp`	발송 시각 (Unix 초)
`webhook-signature`	`v1,<base64 서명>` — 시그니처 검증 참고

다음 단계

이벤트 종류

어떤 일이 생겼는지 알려주는 이벤트와 페이로드예요.

시그니처 검증

위조된 요청을 걸러내는 방법이에요.

재전송과 멱등성

실패 시 재시도 규칙과 중복 없이 처리하는 법이에요.