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

{
  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.

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