포스트백 규격

사용자가 광고를 완료하면 GAD 서버가 매체에 등록된 콜백 URL 로 포스트백을 보냅니다. 매체 서버는 이 요청을 받아 사용자에게 리워드를 지급합니다. SDK 방식과 서버 API 방식이 같습니다.

요청

메서드	POST
주소	매체에 등록한 콜백 URL
Content-Type	`application/json`

본문 필드

필드	타입	설명
`seq`	string	포스트백 고유 ID. 재전송도 같은 값으로 옵니다 — 이 값으로 중복 적립을 막습니다
`media`	string	미디어키
`adKey`	string	광고키
`adTitle`	string	광고명
`uid`	string	참여 때 받은 사용자 ID
`publisher_data`	string \| null	참여 때 data 로 넘긴 값. 넘기지 않았으면 null
`point`	number	사용자에게 줄 리워드(광고 단가 × 매체 리워드 비율, 소수점 버림)

예시

POST <등록한 콜백 URL>
Content-Type: application/json

{
  "seq": "cmv17ned80006stip4updiqxv",
  "media": "<미디어키>",
  "adKey": "staging-ad-2",
  "adTitle": "[스테이징] 참여 광고 2",
  "uid": "user-0001",
  "publisher_data": "order-123",
  "point": 5
}

응답과 재전송

HTTP 200 으로 응답하면 성공입니다. 응답 본문은 보지 않습니다.
3초 안에 응답하지 않으면 실패로 봅니다.
실패하면 1·5·10·60분 뒤에 차례로 다시 보냅니다(최대 4번). 그래도 실패하면 더 보내지 않습니다.
429·503 응답은 재전송 횟수에 넣지 않고 미뤘다가 다시 보냅니다. Retry-After 헤더(초)를 주면 그만큼(30~600초 범위) 기다립니다.
같은 포스트백이 다시 올 수 있습니다. seq 가 같은 요청은 한 번만 지급하도록 처리해 주세요.

콜백 URL 조건

https 주소
포트는 443(또는 생략)
IP 주소가 아닌 공개 도메인 이름(한 단어 이름·내부 전용 이름 제외)
주소에 사용자 정보(user:pass@)를 넣지 않음

스테이징 콜백 URL 은 콘솔의 '내 테스트 매체'에서 매체마다 등록합니다.

스테이징은 GPA 가 허용한 호스트로만 포스트백을 보냅니다. 콜백 URL 을 등록한 뒤 호스트 허용을 요청해 주세요.

콘솔의 상태가 허용 대기이면 아직 발송되지 않습니다. jyi4@gpakorea.com 로 콜백 URL 의 호스트 이름을 알려 주세요.
허용 대기 중에 생긴 포스트백은 버려지지 않습니다. 5분마다 다시 확인하고, 호스트가 허용되면 발송됩니다. 재전송 횟수도 줄지 않습니다.
상태가 허용됨이면 완료 뒤 몇 초 안에 발송됩니다.

콜백 URL 을 등록하지 않은 매체에서 완료된 건은 포스트백이 나가지 않습니다. 광고 참여 전에 먼저 등록해 주세요.

포스트백 발신 IP 가 필요하면 문의 메일로 요청해 주세요.

수신 서버 준비

매체사 개발팀이 포스트백을 받아 리워드를 지급할 HTTPS 주소를 준비합니다. 운영 서버와 테스트 서버를 구분해 등록하세요.

아직 수신 서버가 없으면 SDK 설치, 목록, 상세 화면까지 먼저 확인할 수 있습니다. 포스트백 수신 검증은 서버가 준비된 뒤 진행하거나 jyi4@gpakorea.com 로 GPA KOREA에 시험 지원을 요청해 주세요.

현재 매체사로 보내는 포스트백에는 요청 서명이 포함되지 않습니다. 발신 IP 허용 목록이 필요하면 jyi4@gpakorea.com 로 문의하세요. seq는 중복 지급 방지용 식별자이며 요청의 발신자를 인증하지 않습니다.

GPA KOREA 내부 수신 도구는 매체사 서버의 요청 검증·중복 지급 방지·리워드 지급 구현을 대신하지 않습니다.

운영 환경으로 전환

운영 매체 등록, 미디어키 확인, 콜백 URL 설정은 운영 콘솔에서 합니다. 운영과 스테이징은 같은 GAD 매체사 계정으로 로그인하며 데이터·미디어키·콜백 설정은 환경별로 분리됩니다.

운영 콜백 URL 은 운영 콘솔에서 등록합니다. 호스트 허용 절차는 스테이징에만 있습니다.