Webhooks

Introduction

Webhooks is an event-driven push notification system; when an event (e.g. a rebill) occurs, we deliver a post of data to a script that you designed based on our Webhook Documentation.

Webhooks is an alternative to our Background Post to URL feature and an add-on feature to our ENS system. The Webhooks system is much more robust, providing real-time notifications in addition to covering a greater array of event types.

What's a Webhook?

In general terminology, Webhooks is an API concept of sending real-time push notifications to Webhook endpoints.

  1. Your Webhook endpoint is your previously defined URL. All event notifications will be delivered to your URL.
  2. An Event is an occurrence surrounding your account, e.g., a user reactivating their subscription or a successful sale. Whenever a payment event occurs, you will receive a push notification.
  3. An HTTP POST is the process of submitting data to a specified resource. The data sent is not stored in browser history or in web server logs; you will need a script that will read the data and store it in your database. When it comes to sending data, this is a safe and secure data transfer method.

Simply put, when something happens (an event) with your account, CCBill’s Webhooks will send a notification to your URL (Webhook endpoint), providing you valuable insight into your online business.

Why Would I Want to Use Webhooks?

For Merchants, Webhooks is a way of receiving valuable information as soon as it happens, rather than checking your account’s data continually and getting no valuable data most of the time. In a lot of ways, Webhooks is just like receiving push notifications on your smartphone, i.e. Facebook sends you a notification whenever you receive a friend request. In a similar manner, CCBill Webhooks will send you a notification if, for example, a new sale was successfully performed. You can write this data to a database for record-keeping or pass them to another script.

Webhooks are especially helpful for:

  • Working out your taxes can get vexing, but with CCBill Webhooks you can track your payments easier by logging in an accounting entry any time you’re notified about a successful sale.
  • If you don’t use CCBill’s management system, Webhooks will help you immensely in updating customers’ memberships.
  • Dealing with chargebacks and refunds. You are notified about chargebacks and refunds immediately, thus giving you precious time to act accordingly.

How Webhooks Work

A Webhook is an HTTP POST operation that occurs when something happens (e.g. a sale). It’s like an inverted API endpoint; instead of making an API call, you can have information sent to your callback URL. You register a URL that we will notify each time an account event occurs.

The diagram below exemplifies how CCBill Webhooks work:

How Webhooks work.

What Is Exactly an Event?

As noted, an Event is some action regarding your account. Every push notification is sent as an XML data package and your URL should be a script, such as CGI, PHP, ASP, etc, programmed to receive and parse the information posted by CCBill.

Below you will find a Webhooks Post example.

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

Enabling and Configuring Webhooks

To configure Webhooks:

  1. From the Subaccount Admin, click the Webhooks link on the left side of the screen.
  2. Enter the URL that you wish posts to be directed to in the Webhook URL field.
  3. Select the post types you wish to subscribe to (click All to select all types, or pick and choose any combination of post types by selecting the check box next to it).
  4. Select the Satellite Locations that Webhooks should post to you from. Try to choose a location that is geographically close to the server that the URL you selected in step 2 in order to ensure that posts get to your URL as quickly as the can. The satellite locations are currently:
    • Phoenix, Arizona
    • Ashburn, Virginia
    • Amsterdam, Netherlands
  5. Click Update to save the configuration.

For an in-depth description of Webhooks post types, variables, and other important information, please see the User Guide.

Note: We recommend testing your Webhook configuration before relying on its accuracy. You can do so by creating a CCBill Test account.

Can I Have Multiple URLs Acting as Webhook Endpoints?

After at least one Webhook has been saved you will be presented with the option to edit, remove, or add more. You may add up to four (4) Webhooks, and each may use different URLs if you wish.

Webhooks Events

Webhooks notifications are outlined in the Webhooks Documentation.

Events included are:

Support

If you encounter any issues in setting up Webhooks, please contact Merchant Support and a member of our team will assist you immediately.