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, you don't need to set up postbacks.
Each time your users interact with an offer, you'll automatically receive conversion data as a postback. We send postbacks as GET requests to your webhook.
Basic steps to set up postback:
Enter your webhook URL.
Copy and save your webhook secret key.
Secure your webhook communications.
Configure your webhook to acknowledge successful requests.
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://example.com/postback.php
Extra static URL parameters aren't required or supported.
Macro support
However, you can use macros in query parameter values to map Besitos postback data to the parameter names your system expects. For example, if our system provides a user_id, it can be mapped to your existing field, such as player_id, in the postback URL.
?user_id=1234
?player_id={user_id}
When the postback fires, the macro is replaced with the corresponding value from our system.
This lets you align our attributes with your existing database schema or tracking parameters without changing your internal systems.
For a complete explanation of the data returned via the webhook, see Postback data.
Where 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.
2. Copy and save your postback secret key
Your postback secret key verifies that requests received by your webhook came from Besitos.
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.
Store your secret exactly as generated. Don't trim or modify it.
3. Secure your webhook communications
We recommend two security measures to protect your webhook connection:
IP allowlisting
Webhook hashing
These are optional, but we strongly recommend both to ensure secure, trusted communication.
IP allowlisting
IP allowlisting, or whitelisting, restricts access to your webhook to requests from trusted IP addresses.
Besitos sends postbacks from a static IP address.
To set up IP allowlisting:
Contact your Besitos Account Manager for the postback IP address.
Add the IP address to your server's allowlist.
Webhook hashing
Besitos includes a verifier in each postback that you can use to verify the request.
The verifier is an HMAC-SHA256 hash generated using your webhook secret key and the webhook URL. You can compare the verifier with a hash your server generates to confirm the request is authentic.
To set up webhook hashing:
Remove the
verifierparameter from the end of your webhook URL.Create an HMAC-SHA256 hash of the remaining URL using your webhook secret key.
Compare the generated hash with the
verifiervalue.Accept the request only if the values match.
When generating the hash, preserve the URL's parameter encoding. Re-encoding the URL before hashing can cause the generated hash not to match the verifier.
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');
4. Acknowledge successful postbacks
Your webhook must return an HTTP 200 response when it successfully receives a postback. Responses such as 201, 204, redirects, errors, or timeouts are treated as failed deliveries.
Keep your response time short. Your webhook should acknowledge the request before performing time-consuming processing such as updating a user's balance or writing to a slow database.
If your system needs to perform additional processing, acknowledge the postback first and process the data afterward.
What's next