イベントと取得結果には、キャンペーンのIDとタイトル、ステータス、広告商品のIDと名前、販売方式、予算、広告主の名前とURL、配信期間、広告ユニット・アプリ・ターゲティング・ターゲティングオプションのIDと名前、ターゲティングポリシー、コンテキストターゲティングで選択されたオプションのコンテキストIDが含まれます。広告主のメールアドレスなどの連絡先、クリエイティブ、単価・割増、決済、審査の内容は含まれません。
事前準備
-
次の2つの権限(スコープ)を持つAPIキーが必要です。キーはプロジェクトのオーナーが [設定] > [連携] メニューで発行します。キーの発行方法は連携 & APIキーを参照してください。
-
campaign:subscribeはAPIキーの作成時に初期状態で選択されていないため、自分で選択してください。発行済みのキーの権限は変更できません。 -
イベントを受け取るサーバーには、インターネットからアクセスできる
httpsのURLが必要です。
基本情報
Webhookの登録
イベントを受け取るURLを登録します。登録できるのはプロジェクトごとに1つで、すでに登録済みの設定がある場合はこのリクエストで更新します。リクエスト
リクエストボディ
- 登録済みの設定は丸ごと置き換えられます。一部だけを変える場合も、希望する設定をすべて送信してください。たとえば
eventsを省略すると、すべてのイベントを受け取る設定に戻ります。 - 上記2つ以外のフィールドを送ると
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で送信します。
イベントの種類
- 1回の変更で送信されるイベントは最大1件です。同時に変わったほかの値は、そのイベントの
payloadに含まれます。 booking.updatedは、パブリッシャーに表示される値が実際に変わった場合にのみ送信されます。ターゲティングオプションが削除されてキャンペーンのターゲティング条件が変わった場合は送信されます。- 次の場合はイベントが送信されません。変わった値は、次のイベントや予約済みキャンペーンの取得に反映されます。
- 広告商品、広告ユニット、アプリ、ターゲティング、ターゲティングオプションの名前が変わった場合
- クリエイティブが承認・却下・変更された場合
- パブリッシャーが新しいターゲティングオプションを作成するか、下位オプションをオプショングループの外に移動して、予約済みキャンペーンにそのオプションの設定が自動で付いた場合
booking.startedとbooking.finishedは、日時を過ぎてから最大1時間遅れて届くことがあります。正確な日時はpayload.startTimeとpayload.endTimeで確認してください。2つのイベントは、日時を過ぎてから24時間以内に1回だけ送信されます。
リクエストヘッダー
イベントボディ
リクエスト例
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は署名した日時(エポックミリ秒)です。現在時刻との差が5分を超える場合は拒否してください。- 再送のたびに
tと署名は新しく生成されますが、ボディ(eventIdとtimestampを含む)は同じです。 - どのAPIキーで署名されたかは
x-adrop-key-idで確認します。キーの交換中は、両方のキーで署名されたイベントが届く場合があります。
Node.js(Express)の例
レスポンスと再送
- イベントを処理したら、10秒以内に
2xxで応答してください。レスポンスボディは使われません。時間のかかる処理は非同期に回し、先に応答してください。 - 一時的な障害の場合は
5xxで応答してください。3xxと4xxは再送されません。
イベント処理のルール
eventIdで重複を除外してください。 同じイベントが最大5回届くことがあります。処理済みのeventIdが届いた場合は再処理せず、2xxで応答してください。eventIdは処理が成功したあとに記録してください。そうすれば、保存に失敗して5xxで応答したイベントが再送されたときに、もう一度処理できます。- 到着順に頼らないでください。 再送や同時に起きた変更のため、順序が入れ替わって届くことがあり、
eventIdの大小でも順序はわかりません。キャンペーンごとに最後に適用したtimestampを保持し、それより小さいtimestampのイベントだけを無視してください。同じ値の場合は適用します。 payloadで上書きしてください。payloadは毎回キャンペーンの全情報のため、campaignIdごとに上書きすれば、イベントを取りこぼしたり順序が入れ替わったりしても最新の状態にそろいます。任意フィールドのないpayloadで上書きすると、以前に保存した名前も消えます。eventTypeは変化、statusは状態です。 2つの値は常に対応するとは限りません。たとえば、終了前に承認が取り消されたキャンペーンのbooking.cancelledはstatusが심사중で、一時停止中に終了したキャンペーンのbooking.finishedは종료됨です。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
以前のキーを廃棄する
コンソールで以前のキーを廃棄し、受信サーバーからも以前のキーの検証を削除します。
セキュリティの推奨事項
- APIキーはシークレット管理ツールなど安全な場所にのみ保管し、設定ファイルやリポジトリ、メッセンジャーで共有しないでください。
- キーが漏えいした可能性がある場合は、すぐにコンソールで廃棄してください。廃棄はすぐに反映され、そのキーで登録したWebhookも無効になります。
- 署名の検証に失敗したリクエストは処理しないでください。アクセスログでは
x-adrop-signatureの値をマスクしてください。
予約済みキャンペーンの取得
予約済みキャンペーンを取得します。Webhookを初めて登録したあとに現在の状態を合わせたり、取りこぼしたイベントを復旧したりするときに使います。campaign:read権限が必要です。
取得対象は、承認済みのキャンペーンのうち、終了日時を過ぎていないもの(配信中または開始前)です。各項目は、イベントのpayloadと同じキャンペーン情報の構造です。
予約済みキャンペーン一覧の取得
- 終了日時(
endTime)が遅い順、同じ場合はキャンペーンIDの降順に並びます。 - レスポンスに
nextがある場合は、次のページがあります。nextの値をそのまま次のリクエストのnextに指定してください。最後のページにはnextがありません。
リクエスト例
レスポンス例
全件同期の例
booking.cancelledイベントで確認してください。
予約済みキャンペーンの個別取得
リクエスト例
- レスポンスは、一覧の
itemsの1項目と同じ構造です。 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をサーバーから管理する方法