If you're using our iFrame or API integration, you'll need to set up a webhook on your server to receive postbacks. However, if you're using our Wallet service, postback setup is not required.
Each time your users interact with an offer, you'll automatically receive conversion data as a postback. This makes it easy to get the information you need without the complexities of a two-way API.
Basic steps to set up postback:
Enter your webhook URL
Copy and save your webhook secret key
Secure your webhook communications
Step 1 - Enter your webhook
First, get a webhook URL from your server, copy it, and enter it into your Besitos Admin portal.
Here's an example of a webhook URL:
https://stage.kashkick.com/postback.php
Extra parameters are neither required nor supported. For a complete explanation of the data returned via the webhook, refer to Postback data.
To enter your webhook URL:
Log in to your Besitos Admin portal.
Click Settings on the sidebar.
Enter your server's webhook URL in Webhook URL.
Step 2 - Copy and save your postback secret key
Keep your postback secret in a safe place. You'll need it later to protect the webhook.
To get your secret key:
Click Add New Secret.
Click Save.
Copy your secret key and store it securely.
Share your webhook URL with your Besitos Account Manager.
Step 3 - Secure your webhook communications
We take the security of your data seriously. That’s why we recommend two security measures to protect your webhook connection:
IP whitelisting
Webhook hashing
These are optional, but we strongly recommend both to ensure trusted and secure communication.
IP whitelisting
IP whitelisting, or allowlisting, restricts network access to specific IP addresses to:
Prevent unauthorized access
Protect against data breaches
Ensure only trusted devices can access systems
We send data via the webhook from a static IP address to your server.
To set up IP whitelisting:
Contact your Besitos Account Manager for the IP address.
Add the IP address to your server's whitelist.
Webhook hashing
Every time we send data through the webhook, we include a verifier in the query parameter, allowing you to verify the message. The verifier is a cryptographic hash generated from the webhook secret key and your webhook URL (see Step 2 - Copy and save your postback secret key). You can use the verifier to check the integrity of each GET you receive from Besitos.
To set up webhook hashing:
Remove the verifier parameter from the end of your webhook URL.
Create an HMAC of the remaining URL using the SHA256 algorithm and your webhook secret key set during postback setup.
Compare the generated hash with the one in the verifier parameter. If they match, the request is authentic and secure.
hash_hmac('sha256', $webhook_url, $webhook_secret)Example
Example
// securely supply the static whitelist ip and your secret webhook key using env variables
define('WHITELIST_IP', $_ENV['WHITELIST_IP']);
define('SECRET_KEY', $_ENV['SECRET_KEY']);
// verify the static IP
if(WHITELIST_IP !== $_SERVER['REMOTE_ADDR']) {
http_response_code(403);
exit('Error: '.$_SERVER['REMOTE_ADDR'].' does not match the whitelisted IP address.');
}
// get the full request url
$protocol = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on' ? "https" : "http");
$request_url = "$protocol://$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URI]";
// parse the url and query string
$parsed_url = parse_url($request_url);
parse_str($parsed_url['query'], $query_string);
// get the verifier value
$verifier = $query_string['verifier'] ?? null;
if (is_null($verifier)) {
http_response_code(422);
exit("Error: missing verifier");
}
// rebuild url without the verifier
unset($query_string['verifier']);
$hashless_url = $protocol.'://'.$parsed_url['host'].$parsed_url['path'].'?'.http_build_query($query_string, "", "&", PHP_QUERY_RFC3986);
// calculate the hash and verify it matches the provided one
$calculated_hash = hash_hmac('sha256', $hashless_url, SECRET_KEY);
if ($calculated_hash !== $verifier) {
http_response_code(422);
exit('Error: invalid verifier');
}
// valid, it is safe to process the webhook
http_response_code(200);
exit('OK');
What's next