연동가이드

웹훅 (Webhook) ​

웹훅(Webhook)을 통해 토스플레이스 서비스에서 발생한 이벤트를 실시간으로 수신할 수 있어요.

개요 ​

  • 웹훅은 등록한 endpoint로 토스플레이스 서버가 HTTP POST 요청을 전송하는 방식으로 전달돼요.
  • 웹훅은 최소 한 번 전달(at-least-once) 정책으로 전달돼요. 동일 이벤트가 재전송될 수 있으므로 수신 측은 처리에 있어 멱등성을 고려해야 해요.

웹훅 설정 ​

웹훅 설정 안내

웹훅 설정은 개발자센터에서 직접 가능해요.

  1. 개발자센터의 내 애플리케이션에서 생성한 OpenAPI를 찾아요.
  2. 웹훅 메뉴의 생성 버튼을 클릭하여 진입해요.
  3. 설정 정보 입력 후 웹훅을 생성해요.

웹훅설정

웹훅 설정 시 유의해야 할 설정값은 다음과 같아요.

  • 수신 주소(Payload URL): 웹훅 이벤트가 전달될 HTTP endpoint 주소예요.
  • 수신 범위(Event trigger): 수신할 이벤트 종류를 지정할 수 있어요.
  • 서명 정보(Secret Key): 웹훅 이벤트 서명을 검증하기 위한 비밀 키예요.

웹훅을 설정하면, 지정한 endpoint로 해당 앱이 설치된 여러 매장의 웹훅 이벤트가 전달돼요. Payload에 매장 ID (merchantId)가 포함되어 매장을 서로 구분할 수 있어요.

웹훅 HTTP 전송 규약 ​

요청 ​

  • Method: POST
  • Content-Type: application/json
  • Success: 수신 측이 HTTP status code 2xx 로 응답하면 전달 성공으로 처리해요.

HTTP 요청 Header ​

HTTP 요청 헤더TypeRequired설명예시
x-toss-event-idstring✅요청 추적을 위한 trace id예요. 수신 측 로그에 함께 남기는 것을 권장해요. 토스플레이스로 기술 지원 요청 시 함께 제공하면 도움이 돼요."000000000000000000000000"
x-toss-webhook-idstring✅웹훅 이벤트 식별자(멱등 키)예요. 동일 이벤트 전송 재시도 시에 같은 값을 가져요. 이벤트 간의 순서를 판단해야 할 경우 이 값을 기준으로 순서를 결정할 수 있어요."000000000000000000000000"
x-toss-delivery-idstring✅전송 시도 식별자예요. 전송 재시도마다 새 값이 부여돼요."000000000000000000000000"
x-toss-timestamptimestamp (epoch milliseconds)✅웹훅 전송 시각이에요.1700000000000
x-toss-signaturestring✅Payload 검증을 위한 서명 값이에요. 보안을 위해 사용을 권장해요."v1=2f5e0c...d12a"

HTTP 요청 Body ​

Payload 단락을 참조하세요.

타임아웃 및 재시도 ​

  • 토스플레이스는 웹훅 수신 측 응답이 지연되어도 서버 안정성이 영향을 받지 않도록 짧은 타임아웃과 재시도 정책을 적용해요.
  • 네트워크 오류, 타임아웃, 3xx/4xx/5xx 응답은 실패로 간주하고 재시도할 수 있어요.
  • 웹훅 전송 실패가 반복되어 전송이 불가능하다고 판단되면, 토스플레이스 서버가 해당 endpoint로의 웹훅 전송을 중단할 수 있어요.

멱등성(Idempotency) ​

웹훅 수신 측은 x-toss-webhook-id를 멱등 키로 사용하여 중복 처리를 방지해야 해요.

웹훅 서명(Signature) 검증 (권장) ​

웹훅 수신 측은 x-toss-signature를 검증하여 Payload 위변조 및 위장 요청을 방지할 수 있어요.

서명 생성 규칙 ​

  • 알고리즘: HMAC-SHA256
  • Key: App에 발급된 Webhook 서명 secret
  • Message: <x-toss-timestamp>.<rawRequestBody> (UTF-8 인코딩)
  • 출력: Message의 HMAC 결과를 hex 인코딩 후 v1= Prefix를 붙여 x-toss-signature 웹훅 요청 HTTP Header에 설정

서명 검증 ​

웹훅 수신 측은 다음을 권장해요.

  • x-toss-timestamp가 현재 시각과 너무 크게 차이나는 요청은 거부해요.
  • x-toss-signature를 서명 생성 규칙에 따라 검증하여 Payload 위변조 및 위장 요청을 방지해요.
  • 서명 검증 실패 시 401 또는 400으로 응답해요.

서명 예시 ​

서명 Key 예시:

GA1k8THAGeGihd_Z0rW0MqpRTDQGYIktHBfmCWbsZn0

웹훅 이벤트 요청 예시:

POST /webhook HTTP/1.1
Host: example.com
Content-Type: application/json
x-toss-event-id: 000000000000000000000000
x-toss-webhook-id: 000000000000000000000000
x-toss-delivery-id: 000000000000000000000000
x-toss-timestamp: 1767225600000
x-toss-signature: v1=0398718113ed9a277320953cd613e4ecad4fed4a6dc843064ec311e14368774e

{"id":"000000000000000000000000","type":"_test.v1","createdAt":"2026-01-01T00:00:00.000Z","merchantId":42,"app":"my-awesome-app","data": {}}

웹훅 송신 IP ​

토스플레이스 서버에서 웹훅을 전송할 때, 송신 IP는 다음과 같아요. 웹훅이 정상적으로 수신되지 않는 경우, 다음 IP로부터의 요청이 방화벽에서 허용되어 있는지 확인해주세요.

  • 15.165.6.198

Payload ​

WebhookEvent ​

FieldTypeRequiredDescriptionExample
idString✅웹훅 이벤트 식별자예요. x-toss-webhook-id 요청 헤더와 동일해요."000000000000000000000000"
typeString✅웹훅 이벤트 타입이에요."app.installation.created.v1"
createdAttimestamp✅웹훅 이벤트 발생 시각이에요."2026-01-13T00:00:00Z"
merchantIdLong✅웹훅 이벤트가 발생한 매장 ID예요.42
appString✅웹훅 이벤트를 수신하는 App 정보예요."myPackageName"
dataObject✅웹훅 이벤트 타입별 Payload예요.-