What is a Webhook?
A WebHook is an HTTP POST request that occurs when a specific action happens in your iDevAffiliate admin center, i.e. it's a simple event-notification via HTTP POST. iDevAffiliate uses webhooks to notifiy your custom application in real time about specific events.
Some samples showing how you might use Webhooks for your own custom application:
- Receive a request from iDevAffiliate every time a new account is created to send a custom email or text message, etc.
- Get notified everytime a new commission or debit is created, keeping your own accounting functions in sync.
Configuring Your Webhook
Login to your iDevAffiliate admin center and go to Tools > Webhooks. Enter the Webhook URL to receive Webhooks.
Webhook Log
Each time a webhook is called, a log is created. You can view the login your adminc center at Tools > Webhooks > Webhook Log (tab).
| Webhook Name | Webhook | Description |
|---|---|---|
| commission.created | Commission Created | Triggered when a new commission is created. |
| commission.approved | Commissin Approved | Triggered when a commission is approved. |
| commission.declined | Commission Declined | Triggered when a commission is declined. |
| payment.completed | Payment Completed | Triggered when a payment is completed. |
| affiliate.created | Affiliate Created | Triggered when a new affiliate account is created. |
| affiliate.approved | Affiliate Approved | Triggered when a new affiliate account is approved. |
| affiliate.terminated | Affiliate Terminated | Triggered when an affiliate account is terminated. |
| debit.created | Debit Created | Triggered when a new debit is created. |
| debit.removed | Debit Removed | Triggered when an unsettled debit is removed. |
| debit.settled | Debit Settled | Triggered when a debit is settled, after payment. |
Event Data
The request body is a JSON object with the following fields. Each event type is listed below showing data to be consumed.
Available Webhook Data: commission.created | commission.approved | commission.declined
| Name | Type | Description |
|---|---|---|
| event | string | Event type that has occured. |
| webhook_timestamp | number | Unix timestamp for the event that has occured. |
| webhook_date | date | Rendered date taken from webhook_timestamp. |
| webhook_time | time | Rendered time taken from webhook_timestamp. |
| affiliate_id | number | Affiliate ID for the event that has occured. |
| username | string | Affiliate username for the event that has occured. |
| first_name | string | Affiliate first name for the event that has occured. |
| last_name | string | Affiliate last name for the event that has occured. |
| string | Affiliate email address for the event that has occured. | |
| order_number | string | Order number for the event that has occured. |
| commission_amount | string | Commission amount for the event that has occured. |
| sale_amount | string | Sale amount for the event that has occured. |
| currency | string | Currency for the event that has occured. |
| cart_integration | string | Cart integration for the event that has occured. |
| tid_1 | string | TID 1 for the event that has occured. |
| tid_2 | string | TID 2 for the event that has occured. |
| tid_3 | string | TID 3 for the event that has occured. |
| tid_4 | string | TID 4 for the event that has occured. |
| sub_id | string | Sub ID for the event that has occured. |
| commission_timestamp | number | Unix timestamp for the commission as it was created. |
| commission_date | date | Rendered date taken from commission_timestamp. |
| commission_time | time | Rendered time taken from commission_timestamp. |
Available Webhook Data: payment.completed
| Name | Type | Description |
|---|---|---|
| event | string | Event type that has occured. |
| webhook_timestamp | number | Unix timestamp for the event that has occured. |
| webhook_date | date | Rendered date taken from webhook_timestamp. |
| webhook_time | time | Rendered time taken from webhook_timestamp. |
| affiliate_id | number | Affiliate ID for the event that has occured. |
| username | string | Affiliate username for the event that has occured. |
| first_name | string | Affiliate first name for the event that has occured. |
| last_name | string | Affiliate last name for the event that has occured. |
| string | Affiliate email address for the event that has occured. | |
| payment_amount | string | Payment amount for the event that has occured. |
| currency | string | Currency for the event that has occured. |
Available Webhook Data: affiliate.created | affiliate.approved | affiliate.terminated
| Name | Type | Description |
|---|---|---|
| event | string | Event type that has occured. |
| webhook_timestamp | number | Unix timestamp for the event that has occured. |
| webhook_date | date | Rendered date taken from webhook_timestamp. |
| webhook_time | time | Rendered time taken from webhook_timestamp. |
| affiliate_id | number | Affiliate ID for the event that has occured. |
| username | string | Affiliate username for the event that has occured. |
| first_name | string | Affiliate first name for the event that has occured. |
| last_name | string | Affiliate last name for the event that has occured. |
| string | Affiliate email address for the event that has occured. | |
| payable | string | Payable details for the event that has occured. |
| company | string | Company details for the event that has occured. |
| address_1 | string | Address information for the event that has occured. |
| currency | string | Currency for the event that has occured. |
| address_2 | string | Address information for the event that has occured. |
| city | string | City information for the event that has occured. |
| state | string | State information for the event that has occured. |
| zip | string | Zip code information for the event that has occured. |
| country | string | Country information for the event that has occured. |
| phone | string | Phone information for the event that has occured. |
| fax | string | Fax information for the event that has occured. |
| website_url | string | Website URL information for the event that has occured. |
| ip_address | string | IP address information for the event that has occured. |
| payment_method | string | Payment method information for the event that has occured. |
| signup_date_timestamp | number | Unix timestamp for the new account as it was created. |
| signup_date | date | Rendered date taken from signup_date_timestamp. |
Available Webhook Data: debit.created | debit.removed | debit.settled
| Name | Type | Description |
|---|---|---|
| event | string | Event type that has occured. |
| webhook_timestamp | number | Unix timestamp for the event that has occured. |
| webhook_date | date | Rendered date taken from webhook_timestamp. |
| webhook_time | time | Rendered time taken from webhook_timestamp. |
| affiliate_id | number | Affiliate ID for the event that has occured. |
| username | string | Affiliate username for the event that has occured. |
| first_name | string | Affiliate first name for the event that has occured. |
| last_name | string | Affiliate last name for the event that has occured. |
| string | Affiliate email address for the event that has occured. | |
| debit_amount | string | Debit amount for the event that has occured. |
| debit_reason | string | Debit reason for the event that has occured. |
| debit_timestamp | number | Unix timestamp for the debit as it was created. |
| debit_date | date | Rendered date taken from debit_timestamp. |
| debit_time | time | Rendered time taken from debit_timestamp. |
Responding to Webhooks
Your app should return a 200 OK HTTP status code in reply to a Webhook. This lets iDevAffiliate know that you received the Webhook.
Webhooks Security
There are many ways to secure your application. Our sample shows you how you can restrict the Webhook to only your server IP. An example (using PHP) is below.
Copy
if ($_SERVER['REMOTE_ADDR'] != 'xx.x.xxx.xx') { // Your server IP here.
header('HTTP/1.1 403 Forbidden');
mail('mail@mail.com', 'Webhook called from invalid IP.', $_SERVER['REMOTE_ADDR']); // Send an email notification.
exit;
}Webhook Example
Below is a PHP example. This is code you could use in your own custom webhook file to be called by iDevAffiliate.
Copy
<?PHP
if ($_SERVER['REMOTE_ADDR'] != 'xxx.xxx.xx.xx') { // server IP here
header('HTTP/1.1 403 Forbidden');
mail('mail@mail.com', 'Webhook called from invalid IP.', $_SERVER['REMOTE_ADDR']);
exit;
}
$json = file_get_contents('php://input');
$idev = json_decode($json, true);
if (empty($idev['event'])) {
header('HTTP/1.1 400 Bad Request');
exit;
}
switch ($idev['event']) {
case 'commission.created':
// Your code here.
// Example:
// $ordernumber = $idev['order_number'];
break;
}
header("HTTP/1.1 200 OK");
?>