BASICS: Posting and Postbacks with TrackDrive
Written by Rich Nolan
Updated at June 22nd, 2023
In a nutshell, call platforms have to communicate with each for many reasons. It has always been a good practice to send any data you have about a caller to a buyer if you have it and to request it as a buyer if your traffic source has it. With the invention of PING/POST, posting data between systems is now being required by both buyers and traffic sources in order to protect data, and also speed up the process of connecting calls.
This document explains what you need to ask for based on if you are the buyer or the traffic source, and in the TrackDrive platform what to provide when you are asked for it.
Posting Data to Buyers and
Getting a Postback from Buyers
(you are the Traffic Source - aka: affiliate/publisher/vendor)
In this situation, the following is needed:
1) Get POSTING INSTRUCTIONS from your buyer, and ensure they have a field that the “trackdrive_call_uuid” and “trackdrive_subdomain” can be sent in. They may create a custom field for you or inform you to send these values in any field available like a subid or another available field.
2) Provide POSTBACK INSTRUCTIONS as follows:
NOTE: There are two ways to authenticate the Postback from the buyer. One is to send “auth_token” in the data payload, the other is to use “Authorization: Basic BASIC_AUTH_PASSWORD_HERE” in the header of the webhook. Since the “auth_token” method can be set as a global postback and at the time of this article Basic Auth can not be global, the preferred method until the Basic Auth can be a global header is to use the “auth_token” in the payload.
NOTE: you may optionally have the buyer send Revenue, or set the conversion setting in the buyer record to API Postback with the agreed upon revenue set in the Buyer Conversion Settings. The “data” is also optional if you don't need the buyer to send back any additional data. For example, you may or may not want the buyer reference for the conversion, or other data like first and last name if they are willing to send back data they gathered after the call was transferred to them.
PostBack to TrackDrive using Basic Auth
Post Back Call Data to TrackDrive using Basic Header Authorization
URL: Below is the URL to use but you MUST replace the TrackDrive Subdomain to the Subdomain of the TrackDrive client:
https://{TRACKDRIVE_SUBDOMAIN_HERE}.trackdrive.com/api/v1/calls/update_call/{TRACKDRIVE_CALL_UUID}
NOTE: The payload below is set
HTTP Method: POST
Headers:
Content Type: application/json (NOTE: If doing a POST URL or GET do not use this header)
Authorization: Basic {Basic Auth Token Here - see below}
Body:
For ease in setting this up, the JSON Payload is below, just fix the fields in squiggly brackets.
{
"buyer_converted": "true",
"revenue": "[Call:ConversionPayout]",
"offer_converted": "true"
“post_call_tokens” : {
}
}
The JSON Payload above is the minimum setup to use to Postback to TrackDrive. However, more data can be appended if available in the Buyer data. For example, the “first_name” and “last_name” may be fields a TrackDrive user wants back in the hashed “post_call_tokens” values of the Postback. However, additional data is usually not sent on Postbacks for most tracking purposes, and the example payload above is all you will need.
Obtaining Your Basic Auth Header Token:
Basic Authorization is required to update calls in TrackDrive. If you can't set headers in your data, we do have an option to send authorization in the payload, but please reserve the use of this on an as needed basis. Authorization should be done in the Header and not the Payload for more security.
An Authorization Token may be obtained from your TrackDrive client or using one you assign to yourself on the TrackDrive account associated with your email. To get your own Basic Auth Token from TrackDrive to use in headers, switch to YOUR account on TrackDrive and use the following instructions as pictured:
Navigate to Integrations/API & Access Tokens
Click on New Button to add a new Auth Token
Description: Give a good name for this Access Setup. The example above has “Global Basic Auth for My Email Address”
Data Access: Pick Superuser Access
Resource Access: Check the box for Grant unlimited access to all resources.
NOTE: Some legacy systems we realize don't allow you access to put in Header values. In this case, you can send the “auth_token” with the API key you find your Profile on TrackDrive; however, permission must be granted in your TrackDrive Client's Team Setup for you to allow the legacy token to be used.
BASICS: PostBack to TrackDrive with
On Buyer Platform
Post Back Call Data to TrackDrive using “auth_token”
URL:
Below is the URL to use but you MUST replace the TrackDrive Subdomain to the Subdomain of the TrackDrive client. HINT: TrackDrive will send “trackdrive_subdomain” as a field along with “trackdrive_call_uuid" . If you can do Token Replacement in the Subdomain part of the domain name, you can make this a GLOBAL postback for all of TrackDrive Traffic Sources.
https://TRACKDRIVE_SUBDOMAIN_HERE.trackdrive.com/api/v1/calls/update_call/TRACKDRIVE_CALL_UUID_HERE
Example 1) Your platform can not replace the SubDomain :
https://example_subdomain.trackdrive.com/api/v1/calls/update_call/[trackdrive_call_uuid]
Note that example_subdomain is a static value you type in that spot, while the TrackDrive Call UUID is replacing the value from the database on your system using what is called Token Replacement. In this example, we are using square brackets for token replacement, but many systems use different methods that you must know. If you are not sure, ask your Platform Support Team. For example, while TrackDrive uses [token_name], others might do {{token_name}} and ViciDial is really unique: --A--token_name--B--
There really is no rhyme or reason to what a programmer decides to use to indicate you want to replace that part of the URL or Data being sent with information from the database, they choose a pattern they don't think would ever happen naturally in any string.
Example 2) Your platform can replace the SubDomain :
https://[trackdrive_subdomain].trackdrive.com/api/v1/calls/update_call/[trackdrive_call_uuid]
HTTP Method:
POST
Headers:
Content Type: application/json (NOTE: If doing a POST URL or GET do not use this header)
Body:
For ease in setting this up, the JSON Payload is below, just fix the highlighted fields
{
"auth_token": "REPLACE_ME: With Your TrackDrive Authorization Token",
"buyer_converted": "true",
"revenue": "REPLACE_ME: Using Token Replacement OR a Static Dollar Amount",
"offer_converted": "true",
"post_call_tokens": {}
}
Find your Auth_Token when you login to TrackDrive and use the User Menu/Profile. Your TrackDrive Traffic Source can not Provide this to you, but you may reach out to support@trackdrive.com from the email on your TrackDrive Team Account, and we can get this for you.
The JSON Payload above is the minimum setup to use to Postback to TrackDrive. However, more data can be appended if available in the Buyer data. For example, the “first_name” and “last_name” may be fields a TrackDrive user wants back in the hashed “post_call_tokens” values of the Postback. However, additional data is usually not sent on Postbacks for most tracking purposes, and the example payload above is all you will need.
NOTE: Your TrackDrive Traffic Source (publisher/affiliate/vendor) must have the email address you login to TrackDrive with on a TEAM that has permissions to update a call.
NOTE: It is preferable that the Authorization uses the method with credentials in the Header vs the Data on the webhook. Contact TrackDrive support for help in getting your Private and Public Keys for Basic Authorization.
Setting Buyer Permissions on a Team
On Traffic Source TrackDrive Platform
Giving the Buyer Permission to Update Calls
The postback won't work unless the Buyer has a Team setup in TrackDrive with Permissions to update the call. The best way to make a buyer team is to edit the buyer record, go down to the Team Access section and add a new team for a buyer by entering the email address. Once a buyer team is added, you can see the permissions under Company/Teams and edit the team permissions as pictured below:
Getting Data from Traffic Sources and
Doing a Postback to Traffic Sources
(you are the Buyer - aka: target/advertiser)
In this situation, the following is needed:
1) Provide POSTING INSTRUCTIONS to your Traffic Source. Depending on what they have for Postback Instructions, they will have a piece of data they need to send to TrackDrive. The standard field for this on TrackDrive is “traffic_source_lead_id”, but any available field can be used by the Traffic Source to send any postback fields. There are quite a few defined fields for the most common platforms TrackDrive interfaces to most often like “ringba_call_uuid” and “retreaver_call_uuid”.
The TrackDrive posting instructions are obtained in the Offer Edit under the Posting Instructions tab. Simply pick the posting instructions you want and then select the traffic source and click on “Get Instruction Link”. This will open the Posting Instructions in a new tab. Just copy the URL and provide that to the Traffic Source.
2) Get POSTBACK INSTRUCTIONS from your Traffic Source. For Ringba and Retreaver, we have a global webhook available, and you will just need to get the unique code to update Ringba, and no code is needed for Retreaver. For other platforms, the Traffic Source will provide how they need data back to them, and you can put a Trigger on the Offer or on the Traffic Source record to perform the Postback on the Trigger of Traffic Source converted.