Webhook Registration (Data Pull Flow)

Document created by catherine.racette on Sep 6, 2018Last modified by catherine.racette on Sep 18, 2018
Version 7Show Document
  • View in full screen mode

For an introduction to this option, please refer to The specified item was not found. documentation.

Data Pull Flow

Before using PubMatic APIs, first generate the API Token. For more information, refer to Getting Started with PubMatic APIs

      

 

Webhook Registration

Once you have your access token, a one-time setup is required before data pull requests can be submitted. If this step is skipped, PubMatic will send an email notification of data availability reports to the user associated with the pubtoken instead of the endpoint.

 

If a change is required in the endpoint, this step can be repeated with a different endpoint URL, as explained below.

Note: {id}= the publisher ID in PubMatic.

                         
DescriptionMethod PathHTTP Method TypeBody Content
Add a new endpoint to the list of existing endpoints

/v1/analytics/ptp/publisher/notification/update/{id}

PUT

{"webhookURLs":[{"url":"http://publisher-endpoint-address1"}],"emailAddresses":"<publisher_email>"}

Where, url = A new endpoint where PubMatic will send the notification for data availability in addition to the original list.

Remove given endpoint from the list/v1/analytics/ptp/publisher/notification/update/{id}DELETE

{"webhookURLs":[{"url":"http://publisher-endpoint-address2"}],"emailAddresses":"<publisher_email>"}

 

Where, url = Remove given endpoint from a list of existing endpoints.

Note: If empty string is passed, PubMatic will not do anything.   

                         

 

Data Pull Flow

1. Submit data pull requests or schedule reports

The publisher submits data pull requests with GET method to the endpoint provided by PubMatic. Alternatively, the publisher can schedule reports for a specific frequency.

DescriptionMethod Path
HTTP Method Type
Request Query Parameters
Expected Response
Submit data pull requests to PubMatic/v1/analytics/ptp/publisher/{id}GET

dateUnit=Supported time units. Example: date

 

dimensions=list of supported dimensions separated by comma. Example: siteId,countryId,date,keyValue

 

metrics=list of supported metrics separated by comma. Example: revenue,paidImpressions,totalRequests

 

fromDate=Start date of data retrieval. Example: 2018-01-01

 

toDate=End date of data retrieval. Example: 2018-01-02

{"queryId":"1234abc"}

 

Note: Publisher must store above "queryId" to pull data for this request and to check the status of the data availability/report status. If dateUnit, dimensions, metrics or date ranges are not supported or invalid, PubMatic will return error.

Example 

http://PubMatic_endpoint/v1/analytics/ptp/publisher/*resource_id*?dateUnit=date&dimensions=siteId,countryId,date,keyValue&metrics=revenue,paidImpressions,totalRequests&fromDate=2018-01-30&toDate=2018-01-31'

2. Obtain the status of the request

Get the status of whether the report query was submitted successfully or whether to abort the data pull request.

DescriptionMethod Path
HTTP Method Type
Request Query Parameters
Expected Response
Status of the report query is successful/v1/analytics/ptp/publisher/status/{id}GET

queryId=Returned query id in step 1. Example: 1234abc

{"queryId":"1234abc", "status":"COMPLETED"}

 

Possible statuses:

COMPLETED: Data is available to be pulled.

JOB_SUCCEEDED: Job completed the data pull.

JOB_RUNNING: Job to prepare data is running.

FAILED: Data pull failed.

ABORTED: Data pull request aborted.

Abort the data pull request

/v1/analytics/ptp/publisher/{id}

DELETE

queryId=Returned query id from step 1.

Example: 1234abc

200 ok

 

3. PubMatic sends metadata for the data pull in a webhook notification

Once data is available to be pulled, PubMatic sends a webhook notification; a simple HTTP POST notification to the endpoint provided by the publisher.

Description
HTTP Method Type
Expected Response
POST notification with downloadURL to download data from PubMaticPOST

{“queryId”:”1234abc”,“Status”:”COMPLETED”,“downloadURL”:“http://pubmatic_endpoint/v1/analytics/lazy/publisher/artifact/download/{location1}”,"errorCode":null,"errorMessage":null}

 

Where, “downloadURL”= The endpoint from where data in .csv template can be downloaded. Endpoint is present only if status = “COMPLETED”, otherwise it will be empty.

 

Possible statuses:

COMPLETED: Data is available to be pulled.

FAILED: Data pull failed. In this case, there will be an errorCode and an errorMessage as part of the response. Depending upon the error code, we recommend appropriate actions or check with your CSOM/TE. 

Note: If PubMatic does not receive “200 OK”, then PubMatic will retry to send the notification.                  

                       

 

4. Download data

The publisher can connect to the endpoint shared by PubMatic to download the data in CSV format.

DescriptionMethod PathHTTP Method Type
Download data from PubMatic

http://PubMatic_endpoint/v1/analytics/ptp/publisher/artifact/download/{location1}

GET

 

Note: PubMatic will store data for a maximum of 90 days after initial request submission for given queryId.

                         

Attachments

    Outcomes