Webhooks User Guide

This document is a comprehensive guide to CCBill Webhooks and is intended for users with advanced coding skills.

It includes detailed instructions for configuring your system to receive Webhook data. You will learn how to send customer information to the CCBill payment form, the data variables involved, and how those variables are used to track and manage transaction events on your account.

Enable and Configure Webhooks

To configure Webhooks:

1. Log in to the Admin Portal.

2. Use the dropdown menu to select a specific subaccount.

3. Click Webhooks in the left-side menu.

4. In the Webhook URL field, enter the URL where you want to receive posts.

5. Select one of the available Webhooks data formats:

• JSON. Follows the JSON (JavaScript Object Notation) open-standard format and uses the content type application/json.
• URL Encoded. Uses the content type application/x-www-form-encoded (original format).

6. Select the post types you wish to subscribe to. Click All to select all types or individually select checkboxes for specific post types.

7. To minimize latency, select the Satellite Location closest geographically to the server hosting the URL you entered in step four. Available locations include:

• Phoenix, Arizona
• Ashburn, Virginia
• Amsterdam, Netherlands

8. Click Update to save the configuration.

After at least one Webhooks configuration has been saved, you will be presented with the option to edit, remove, add, or select notification versions. You may add up to four (4) Webhooks URLs.

Webhooks Versioning

Since October 2013, Webhooks have supported versioning to ensure backward compatibility. Changes to the Webhooks system will not disrupt existing configurations.

A ChangeLog at the end of this document summarizes changes for each version.

Whenever you create a new Webhooks configuration, it automatically uses the latest Webhooks version. Existing Webhooks configurations created under older versions can optionally be upgraded. Note the following rules for updating existing configurations:

• Adding a new event to an existing configuration will cause only the newly added event to use the latest Webhooks version. Previously configured events will continue to use their original versions.
• Updating the URL of an existing Webhook configuration does not upgrade it to a new Webhook version.

Webhooks IP Ranges

You will receive Webhooks from the following CCBill IP ranges:

• 64.38.212.1 - 64.38.212.254
• 64.38.215.1 - 64.38.215.254
• 64.38.240.1 - 64.38.240.254
• 64.38.241.1 - 64.38.241.254

You can use this information to set up firewall rules or confirm the validity of a Webhook from within your application.

URL Parameters

Webhooks send 4 URL parameters with posts to let you know what type of Webhook is contained in the post. The following parameters are sent:

The URL Parameters comprise the first line in the following Webhooks Post example:

URL Encoded Format

POST /webhooks.php?clientAccnum=999999&clientSubacc=9999&eventType=Expiration&eventGroupType=Subscription HTTP/1.1
X-Allowed-Satellites: PHX,ASH,AMS
Content-Type: application/x-www-form-urlencoded
Content-Length: 102
Host: merchanturl.com
User-Agent: Java/1.6.0_03
Via: 1.1 wmq1.ccbill.com:3129 (squid/2.7.STABLE5), 1.0 internal
Cache-Control: max-age=0
Connection: keep-alive

clientAccnum=999999&clientSubacc=9999&subscriptionId=0913024401000012340&timestamp=2013-01-25 03:22:44

JSON Format

POST /webhooks.php?clientAccnum=999999&clientSubacc=9999&eventType=Expiration&eventGroupType=Subscription HTTP/1.1
X-Allowed-Satellites: PHX,ASH,AMS
Content-Type: application/json
Content-Length: 102
Host: merchanturl.com
User-Agent: Java/1.6.0_03
Via: 1.1 wmq1.ccbill.com:3129 (squid/2.7.STABLE5), 1.0 internal
Cache-Control: max-age=0
Connection: keep-alive
{"clientAccnum":"999999","clientSubacc":"9999","subscriptionId":"0913024401000012340","timestamp":"2013-01-25 03:22:44"}

Variable Reference

CCBill has a set of specified system variables that can be used to pull data from CCBill’s system. Two variable sets are used, one for each of the following situations:

• Payment Form. These variables are used to pre-fill the payment form. Naming the variables correctly, as listed below, will ensure the data is properly stored in CCBill’s system as the variables are intended.
• Return. These variables are sent to the Webhook URL, depending on the transaction's outcome.

In both cases, custom variables will be sent exactly as they were entered. System variable names must be entered exactly as they appear in this list.

Payment Form Variables

The following chart lists each variable that can be pre-filled in the payment form:

The following variables can also be passed into the payment form but are not shown on the form:

Passing Variables to the Payment Form

Variables can be passed to the payment form to pre-fill consumer information. This can be implemented for multi-part forms, custom tracking, and other implementations.

Variables are passed to the payment form from the preceding page through an HTML form or by passing in the variables through a URL string.

URL String Example

https://bill.cbill.com/jpost/signup.cgi?clientAccnum=900000&clientSubacc=0001&formName=211cc&language=English&allowedTypes=0000003761:840,0000004607:840,0000060248:840,0000063750:840,0000060752:840&subscriptionTypeId=0000004657:840

HTML Form Fields

<form action='https://bill.ccbill.com/jpost/signup.cgi' method='POST'>
  <input type='hidden' name='clientAccnum' value='900000'>
  <input type='hidden' name='clientSubacc' value='0001'>
  <input type='hidden' name='formName' value='211cc'>
  <input type='hidden' name='language' value='English'>
  <input type='hidden' name='allowedTypes' value='...'>
  <input type='hidden' name='subscriptionTypeId' value='0000004657:840'>
  <input type='submit' name='submit' value='Join Now'>
</form>

Custom Variables

Custom tracking variables can also be sent to the form. These values will be posted back to the Webhooks URL when the transaction is complete. To define these variables, specify a variable name and a value in the same manner as the other variables being passed.

Optional custom tracking variables can be added manually by creating additional HTML form fields or passing the additional variables into the URL string, depending on the chosen submission method.

The following example shows a basic HTML button code with two custom variables added. The button created will, when clicked, take the consumer to the CCBill payment form while passing in the two custom variables:

Example HTML Button Code with Custom Variables

<form action='https://bill.ccbill.com/jpost/signup.cgi' method=POST>
<input type=hidden name=clientAccnum value='900000'>
<input type=hidden name=clientSubacc value='0001'>
<input type=hidden name=formName value='211cc'>
<input type=hidden name=language value='English'>
<input type=hidden name=allowedTypes value='0000003361:840,0000004657:840,0000060748:840,0000060750:840,0000060752:840'> <input type=hidden name=subscriptionTypeId value='0000004657:840'>
<input type=hidden name=customVarName1 value=customVarValue1>
<input type=hidden name=customVarName2 value=customVarValue2>
<input type=submit name=submit value='Join Now'>
</form>

customVarName1 and customVarName2 are only example variable names. You can assign any name and variable that suits your requirements.

Dynamic Variables in Custom Scripts

Information can also be passed to the CCBill payment form using dynamic variables in a custom script. A custom HTML form can call the script, sending the variables to the CCBill payment form.

The form you create will pass data entered by the consumer to the next form, which will then pass the variables to the CCBill payment form. Upon completion of the transaction, data will be sent to the Webhooks URL.

Perl/CGI Example for Hidden Field Generation

print "<input type=hidden name=customer_fname value='$cust_first_name'>";

Other languages will have different statements and syntax for data output, such as print or echo statements in PHP. Link code can also dynamically generate variables in a similar fashion.

Receiving Data

When a transaction event occurs, CCBill sends variables back to your Webhook URL. These typically mirror the Payment Form variables plus consumer-entered information, along with additional status-related data (e.g., subscriptionId, timestamps, etc.). The exact return variables can differ by event type (sale, cancellation, etc.).

Data can be captured in multiple ways depending on the language in which the Webhooks script is written. For example:

Using PHP to Capture Data

$fname = $_POST["customer_fname"]

Using Perl/CGI to Capture Data

$fname = param("customer_fname")__

Other languages may use different functions to capture POST data. Variable names must match those specified in this guide.

Once the script captures these variable values, the script can handle the data in any manner specified in the script, such as inputting the information into a database.

Webhooks Notifications

The following sections detail the notifications that Webhooks can send to your URL and list the variables included in the notification push. Click the notification type to review individual parameters.

• NewSaleSuccess
• NewSaleFailure
• UpgradeSuccess
• UpgradeFailure
• UpSaleSuccess
• UpSaleFailure
• CrossSaleSuccess
• CrossSaleFailure
• Cancellation
• Expiration
• BillingDateChange
• CustomerDataUpdate
• UserReactivation
• RenewalSuccess (Rebill)
• RenewalFailure (Declined Rebill)
• Chargeback
• Return
• Refund
• Void