Syncing Commission Data via API and Callbacks

Once your users start generating sales, you'll want your system to sync the associated data so that you can show these sales to your users, send push notifications, etc.  There are two ways to get this transaction data: pull them from our API or receive callbacks from our system.  In most cases, you'll want to receive callbacks to keep your system in sync as closely as possible, but you'll also want to hit the API to pull batches of transactions in case a callback wasn't successful.  At this time, we do not re-attempt failed callbacks.

Getting Commission Data via the Wildfire API

To see the API docs for how to fetch transaction data see the API reference.

Getting Commission Data via Callbacks

To set up your callback URL, in your partner admin tool, select the application you want to configure and then select the gear icon.  Here you can enter a callback URL (please ensure it's an HTTPS endpoint) and a callback key.  The callback key can be any value.  The purpose of the callback key is to ensure that the callback is valid (and that a rogue entity is not invoking your callback URL with false data).

Once you have configured your callback settings, if you have any sales data, you can select the "resend callback" icon next to the sale and it will send the callback payload to your callback URL.  You can use this feature to test that your callback settings are configured correctly.

Callback Header Data

A callback request will have a POST body similar to this:

  "ID": "12345678-90ab-cdef-1234-567890abcdef",
  "Type": "Commission",
  "Action": "create",
  "Payload": {
    "ID": 12345,
    "ApplicationID": 42,
    "MerchantID": 123456,
    "DeviceID": 19283,
    "SaleAmount": "321",
    "Amount": "3.211",
    "Status": "PENDING",
    "TrackingCode": "012345-6780a-bcdef0-12345",
    "EventDate": "2019-09-12T01:22:33Z",
    "CreatedDate": "2019-09-13T02:22:33.987654Z",
    "ModifiedDate": "2019-09-13T02:22:33.987654Z",
    "MerchantOrderID": "397254095",
"MerchantSKU": "465056245"

  "CreatedDate": "2019-09-15T00:11:33.987654Z"

And the headers will look like this:

 "User-Agent": "Wildlink_Callback_Bot/1.0",
 "Content-Length": "412",
 "Cache-Control": "no-cache",
 "Content-Type": "application/json",
 "X-Wf-Signature": "sha256=c8abc5baf0a109d3365f90b1f783a9f71eaecd1746fcf39b9b4b1b3417b84cca",
 "Accept-Encoding": "gzip"

Note the "X-WF-Signature" value is the HMAC encoded value of the POST body using a sha256 encoding type and using the Callback Key value that you set.  A PHP example for how to generate this signature (to compare it to the one in the headers to verify that the request is authentic) looks like this:

$post_body = file_get_contents('php://input');
$signature = hash_hmac("sha256", $post_body, $callback_key);

Retry logic

At the time of the writing of this article, Wildfire does not support retrying failed callbacks.  We do intend to add this feature in the future, but in the meantime we recommend using the API calls on a regular basis (i.e. daily) to compensate for the possibility of incomplete callbacks.