Skip to main content
이 문서에서 예약된 캠페인은 광고주가 예약한 캠페인 중 승인을 받아 매체사의 집행 기간과 광고 유닛을 확보한 캠페인을 말합니다. 캠페인 예약 Webhook을 등록하면 예약된 캠페인이 승인·변경·일시정지·재개·취소·시작·종료될 때마다 Adrop이 등록한 URL로 이벤트를 보냅니다. 예약된 캠페인은 API로 직접 조회할 수도 있습니다. 이벤트와 조회 결과에는 캠페인 ID·제목, 상태, 광고 상품 ID·이름, 판매 방식, 예산, 광고주 이름·URL, 집행 기간, 광고 유닛·앱·타겟팅·타겟팅 옵션의 ID와 이름, 타겟팅 정책, 문맥 타겟팅에서 선택한 옵션의 컨텍스트 ID가 담깁니다. 광고주 이메일 같은 연락처, 소재, 단가·할증, 결제, 심사 내용은 담기지 않습니다.

사전 준비

  • 다음 두 권한(scope)이 있는 API 키가 필요합니다. 키는 프로젝트 소유자가 [관리] > [연동] 메뉴에서 발급합니다. 키 발급 방법은 연동 & API 키를 참고하세요.
  • campaign:subscribe는 API 키를 만들 때 기본으로 선택되어 있지 않으므로 직접 선택하세요. 이미 발급한 키의 권한은 바꿀 수 없습니다.
  • 이벤트를 받을 서버에는 외부에서 접근할 수 있는 https URL이 필요합니다.
API 키는 서버에만 보관하고 앱이나 웹 페이지에 넣지 마세요. 이벤트 서명도 이 키로 만들어지므로, 키가 노출되면 바로 폐기하고 새 키로 Webhook을 다시 등록하세요.

기본 정보


Webhook 등록

이벤트를 받을 URL을 등록합니다. 프로젝트당 하나만 등록할 수 있으며, 이미 등록한 설정이 있으면 이 요청으로 수정합니다.

요청

요청 본문

  • 이미 등록한 설정은 통째로 바뀝니다. 일부만 바꾸더라도 원하는 설정 전체를 보내세요. 예를 들어 events를 생략하면 모든 이벤트를 받는 설정으로 돌아갑니다.
  • 위 두 필드 외의 필드를 보내면 400으로 실패합니다.
  • localhost, 사설·내부 주소, 사설 IP로 해석되는 도메인, 해석할 수 없는 도메인, 사용자 정보가 들어간 URL(https://user:pw@host)은 등록할 수 없습니다. 이때는 400 WEBHOOK_CONFIG_URL_NOT_ALLOWED로 실패합니다.
  • 다른 API 키로 다시 등록하면 이후 이벤트는 그 키로 서명됩니다. 키 교체와 폐기를 참고하세요.
  • 등록하기 전에 예약된 캠페인의 이벤트는 따로 전송되지 않습니다. 등록한 뒤 예약된 캠페인 조회로 현재 상태를 한 번 맞추세요.

요청 예시

응답 예시

200과 함께 저장된 설정을 반환합니다.

Webhook 설정 조회

  • 응답은 Webhook 등록의 응답과 같은 형식입니다.
  • 등록한 설정이 없으면 404 WEBHOOK_NOT_FOUND를 반환합니다.
  • active가 false이면 이벤트 전송이 멈춘 상태입니다. 등록에 쓴 API 키가 폐기된 경우이며, 새 키로 다시 등록하면 전송이 재개됩니다.

Webhook 삭제


이벤트 수신

예약된 캠페인이 바뀌면 Adrop이 등록한 URL로 이벤트를 POST로 보냅니다.

이벤트 종류

  • 변경 하나에 이벤트는 최대 한 건입니다. 함께 바뀐 다른 값은 같은 이벤트의 payload에 담깁니다.
  • booking.updated는 매체사에게 보이는 값이 실제로 바뀐 경우에만 보냅니다. 타겟팅 옵션이 삭제되어 캠페인의 타겟팅 조건이 바뀌면 보냅니다.
  • 다음 경우에는 이벤트를 보내지 않습니다. 바뀐 값은 다음 이벤트나 예약된 캠페인 조회에 반영됩니다.
    • 광고 상품, 광고 유닛, 앱, 타겟팅, 타겟팅 옵션의 이름이 바뀐 경우
    • 소재가 승인·반려되거나 바뀐 경우
    • 매체사가 새 타겟팅 옵션을 만들거나 하위 옵션을 옵션 그룹 밖으로 옮겨, 예약된 캠페인에 그 옵션의 설정이 자동으로 붙은 경우
  • booking.started와 booking.finished는 시각이 지난 뒤 최대 1시간 늦게 도착할 수 있습니다. 정확한 시각은 payload.startTime과 payload.endTime으로 확인하세요. 두 이벤트는 시각이 지난 뒤 24시간 안에 한 번만 보냅니다.

요청 헤더

이벤트 본문

요청 예시
모든 이벤트는 같은 구조이며, eventType과 그 시점의 값만 다릅니다. 객체 안의 키 순서는 의미가 없습니다.

캠페인 정보

payload와 예약된 캠페인 조회 결과는 같은 구조입니다. 필드 이름 끝의 ?는 값이 없을 때 키 자체가 빠지는 선택 필드라는 뜻입니다. units의 각 항목에는 다음 필드가 있습니다. targetings의 각 항목에는 다음 필드가 있습니다. 타겟팅과 타겟팅 옵션은 ID로 매칭하고, 이름은 사람이 알아보는 용도로만 쓰세요.
  • contexts와 contextCount는 문맥 타겟팅에서 캠페인이 포함 또는 제외로 선택한 옵션에만 있습니다. 오디언스 타겟팅이나 선택하지 않은 옵션에는 없습니다.
  • 선택한 옵션에 컨텍스트 ID가 없으면 contexts는 [], contextCount는 0입니다.
  • 200개를 넘는 컨텍스트 ID는 문맥 타겟팅 API로 조회하세요.
선택 필드(title, productTitle, advertiser, units의 title·appTitle, targetings의 title·kind, policies의 title·contexts·contextCount)는 이벤트를 보내는 시점에 조회한 값입니다. 해당 항목이 삭제되어 조회되지 않으면 키가 빠지고 ID만 남으므로, 선택 필드가 없어도 오류로 처리하지 마세요.

상태 값

status는 아래 문자열 중 하나입니다. 문자열을 그대로 비교하세요. status는 소재 승인 여부와 관계없습니다.

서명 검증

모든 이벤트 요청에는 x-adrop-signature 헤더가 있습니다. 요청을 처리하기 전에 서명을 검증하세요.
  • signingSecret은 Webhook 등록에 쓴 API 키를 SHA-256으로 해시한 16진수 문자열입니다. 따로 발급받지 않고 API 키로 직접 계산합니다.
  • t는 서명한 시각(epoch 밀리초)입니다. 현재 시각과 5분 넘게 차이 나면 거부하세요.
  • 재전송할 때마다 t와 서명은 새로 만들어지지만, 본문(eventId와 timestamp 포함)은 같습니다.
  • 어느 API 키로 서명했는지는 x-adrop-key-id로 확인합니다. 키를 교체하는 동안에는 두 키가 섞여 올 수 있습니다.
서명은 받은 요청 본문의 원본 바이트로 검증해야 합니다. 파싱한 JSON 객체를 다시 문자열로 만들면 키 순서나 공백이 달라져 검증에 실패합니다.
Node.js(Express) 예시

응답과 재전송

  • 이벤트를 처리하면 10초 안에 2xx로 응답하세요. 응답 본문은 쓰지 않습니다. 오래 걸리는 처리는 비동기로 넘기고 먼저 응답하세요.
  • 일시적인 장애라면 5xx로 응답하세요. 3xx와 4xx는 다시 보내지 않습니다.
서명 오류로 401을 반환하거나, 배포 중에 잠시 404나 429 같은 4xx를 반환해도 그 이벤트는 다시 오지 않습니다. 일시적인 장애에는 5xx로 응답하세요.

이벤트 처리 규칙

  1. eventId로 중복을 거르세요. 같은 이벤트가 최대 5번 도착할 수 있습니다. 이미 처리한 eventId가 오면 다시 처리하지 말고 2xx로 응답하세요. 처리에 성공한 뒤에 eventId를 기록해야, 저장에 실패해 5xx로 응답한 이벤트가 재전송될 때 다시 처리할 수 있습니다.
  2. 도착 순서를 믿지 마세요. 재전송이나 동시에 일어난 변경 때문에 순서가 바뀌어 도착할 수 있고, eventId의 크기로도 순서를 알 수 없습니다. 캠페인마다 마지막으로 적용한 timestamp를 보관하고, 그보다 작은 timestamp의 이벤트만 무시하세요. 같으면 적용합니다.
  3. payload로 덮어쓰세요. payload는 매번 캠페인 전체 정보이므로 campaignId 기준으로 덮어쓰면 이벤트를 놓치거나 순서가 바뀌어도 최신 상태로 맞춰집니다. 선택 필드가 빠진 payload로 덮어쓰면 이전에 저장한 이름도 사라집니다.
  4. eventType은 변화, status는 상태입니다. 두 값이 항상 짝이 맞지는 않습니다. 예를 들어 종료 전에 승인이 해제된 캠페인의 booking.cancelled는 status가 심사중이고, 일시정지 중에 종료된 캠페인의 booking.finished는 종료됨입니다.
  5. budget은 정산 금액이 아닙니다. 정산과 매출 집계에는 리포트 API를 쓰세요.

받을 이벤트 고르기

events로 받을 이벤트를 고를 때 booking.confirmed와 booking.cancelled만 고르면 승인 뒤의 집행 기간, 타겟팅, 광고 유닛, 예산, 광고주 정보 변경(booking.updated)을 놓칩니다. 변경 사항을 반영해야 한다면 booking.updated도 받거나 events를 비워 모든 이벤트를 받으세요.

키 교체와 폐기

이벤트는 마지막으로 Webhook을 등록한 API 키로 서명됩니다. 키를 바꿀 때는 다음 순서를 따르세요.
1

새 API 키 발급

campaign:read와 campaign:subscribe 권한으로 새 API 키를 발급합니다.
2

두 키로 검증하도록 배포

수신 서버가 새 키와 이전 키 모두로 서명을 검증하도록 배포합니다. 어느 키로 서명했는지는 x-adrop-key-id로 구분합니다.
3

새 키로 다시 등록

새 키로 PUT /webhook을 호출합니다. 이후 보내는 이벤트는 새 키로 서명됩니다.
4

교체 기간 두기

등록 시점에 이미 전송 중이거나 재전송을 기다리던 이벤트는 이전 키로 서명되어 도착할 수 있습니다. 10분 이상 기다리세요.
5

이전 키 폐기

콘솔에서 이전 키를 폐기하고, 수신 서버에서도 이전 키 검증을 지웁니다.
Webhook 등록에 쓴 API 키를 폐기하면 Webhook이 비활성화(active: false)되어 이벤트 전송이 멈춥니다. 키를 바꿀 때는 반드시 새 키로 다시 등록한 뒤에 이전 키를 폐기하세요.

보안 권장 사항

  • API 키는 시크릿 관리 도구처럼 안전한 곳에만 보관하고, 설정 파일이나 저장소, 메신저로 공유하지 마세요.
  • 키가 노출된 것 같으면 콘솔에서 바로 폐기하세요. 폐기는 즉시 반영되며, 그 키로 등록한 Webhook도 함께 비활성화됩니다.
  • 서명 검증에 실패한 요청은 처리하지 마세요. 접근 로그에는 x-adrop-signature 값을 가려서 남기세요.

예약된 캠페인 조회

예약된 캠페인을 조회합니다. Webhook을 처음 등록한 뒤 현재 상태를 맞추거나, 놓친 이벤트를 복구할 때 쓰세요. campaign:read 권한이 필요합니다. 조회 대상은 승인된 캠페인 중 종료 시각이 지나지 않은 캠페인(진행 중이거나 시작 전)입니다. 각 항목은 이벤트의 payload와 같은 캠페인 정보 구조입니다.

예약된 캠페인 목록 조회

  • 종료 시각(endTime)이 늦은 순서, 같으면 캠페인 ID 역순으로 정렬합니다.
  • 응답에 next가 있으면 다음 페이지가 있습니다. next 값을 그대로 다음 요청의 next로 보내세요. 마지막 페이지에는 next가 없습니다.
요청 예시
응답 예시
예약된 캠페인 전체를 처음부터 끝까지 읽어 저장하는 예시입니다.
전체 동기화 예시
조회 결과에 없는 캠페인은 취소되었거나 종료된 캠페인입니다. 취소 여부와 시각은 조회 API가 아니라 booking.cancelled 이벤트로 확인하세요.

예약된 캠페인 단건 조회

요청 예시
  • 응답은 목록의 items 항목 하나와 같은 구조입니다.
  • campaignId가 ULID 형식이 아니면 400을 반환합니다.
  • 취소·종료된 캠페인, 승인되지 않은 캠페인, 다른 프로젝트의 캠페인, 없는 캠페인은 모두 404 CAMPAIGN_NOT_FOUND를 반환합니다. 취소 여부는 booking.cancelled 이벤트로 확인하세요.

오류

오류 코드는 응답 본문의 errorCode 또는 message 필드에 담깁니다.

연동 체크리스트

  • campaign:read와 campaign:subscribe 권한이 있는 API 키를 발급해 안전하게 보관했습니다.
  • PUT /webhook으로 https URL을 등록하고, GET /webhook에서 active: true를 확인했습니다.
  • 정상, 위조, 만료된 요청으로 서명 검증을 확인했고, 원본 본문으로 검증합니다.
  • eventId로 중복을 거르고, 보관한 값보다 작은 timestamp의 이벤트만 무시합니다.
  • 10초 안에 2xx로 응답하고, 일시적인 장애에는 5xx로 응답합니다.
  • 선택 필드가 없어도 오류로 처리하지 않고, contextCount가 contexts 개수보다 크면 일부만 담긴 것으로 처리합니다.
  • GET /campaigns로 현재 예약된 캠페인을 처음 한 번 동기화했습니다.
  • 키를 교체할 때 두 키로 검증하는 절차를 갖췄습니다.

관련 문서

연동 & API 키

API 키 발급과 권한 설정 방법

문맥 타겟팅 API

타겟팅 옵션과 컨텍스트 ID를 서버에서 관리하는 방법