Attribution Report

The Attribution API is currently a beta feature. For early access, please reach out to support@heypoplar.com

The Attribution Report endpoint enables you to generate an Attribution Report for up to 6 months of data. The resulting report will be delivered in batches to a webhook URL of your choosing (see below).

Generate attribution report

POST https://api.heypoplar.com/v1/reports/attribution

This endpoint allows you to generate an attribution report from a specified reporting window that will be delivered through a webhook.

Request Body

Name
Type
Description

start_date*

string

YYYY-MM-DD (ISO8601) formatted date for the start of the reporting window.

campaign_id

string

The ID of the campaign for the report.

If not set, the report will contain all campaigns

end_date*

string

YYYY-MM-DD (ISO8601) for the end of the reporting window.

Must be no more than 180 days after start_date

{
  start_date: "YYYY-MM-DD",
  end_date: "YYYY-MM-DD",
  status: "created",
  campaign_scope: "b01cdd5e-5b83-4345-826a-094c823f894b",
  campaign_name: "Campaign Name 1",
  response_webhooks: ["api.yourwebhook.com/attribution_report"]
}

Webhook Setup

This page will only appear if the Attribution API has been enabled for your account

To setup your Attribution API webhook, navigate to Integrations > Attribution Report and click the button to create a new webhook. From here, enter a webhook destination URL of your choosing. To verify the webhook has been setup correctly, use the "Send Test" link and ensure that a 200 response is returned.

Webhook Payload

When the report has finished generating, it will be sent through the webhook that was previously setup.

Field
Description

campaign_id

The ID of the campaign for the report (if provided)

start_date

The starting date for the report window

end_date

The end date for the report window

batch_index

The index of the current batch of results

total_batches

The total number of batches contained in the report

attribution_data

Example Payload

This sample response shows one complete set of data for a "match." Payloads will hold up to 100 matches per batch. The keys found in attribution_data are the same keys used in Download Raw Matches on the transactions page https://app.heypoplar.com/transaction.

{ 
  campaign_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
  start_date: "YYYY-MM-DD",
  end_date: "YYYY-MM-DD",
  batch_index: 0,
  total_batches: 5
  attribution_data: [
    {
      match_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      campaign_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      campaign_name: "Campaign Name 1",
      creative_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      mailing_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      order_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      customer_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      order_date: "2021-12-19 00:00:00 UTC",
      order_total: "283.0",
      order_currency: "USD",
      mailing_cost: 0.46,
      mailing_state: "delivered",
      send_date: "2021-12-16",
      in_home_date: "2021-12-23",
      match_type: "M",
      unique: "false",
      new_buyer: "false",
      email_match: "true",
      billing_address_match: "false",
      shipping_address_match: "true",
      manual_send_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      manual_send_name: "first send",
      metadata: "{\"new_buyer\"=>false}"
    },
    {
      ...
    }
  ]
}
(Optional) Webhook HMAC Verification

HTTP POST payloads contain an X-SLM-Signature HTTP header. This is the HMAC hex digest of the response body. It is generated using the SHA1 hash function with the secret displayed on Integrations > Attribution Report as the HMAC key. You can use this in order to verify the authenticity and integrity of a payload.

Here is an example of verifying authenticity and integrity of a request body using the Ruby library OpenSSL::HMAC.

require 'openssl'
require 'json'

SHARED_SECRET = '591f827adf2f1e348ec3dc2a07e61e59' # found on heypoplar.com Integrations > Attribution Report

request = {
  headers: {
    'X-SLM-Signature': '8b3f7dad2f29e5921d3b36487b16eeaa52c8448e'
  },
  body: {
    'start_date': 'YYYY-MM-DD',
    'end_date': 'YYYY-MM-DD',
    'batch_index': 0,
    'total_batches': 1,
    'attribution_data': []
  }
}

expected_signature = OpenSSL::HMAC.hexdigest(
  OpenSSL::Digest.new('sha1'),
  SHARED_SECRET,
  request[:body].to_json
)
# => '8b3f7dad2f29e5921d3b36487b16eeaa52c8448e'

if request[:headers][:'X-SLM-Signature'] == expected_signature
  # Request verified
end
  

Last updated