SubscriptionBridge: recurring billing and subscription management system - Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== WebHooks ======

===== What is a Webhook? =====

Taken directly from the official WebHook website: 

"The concept of a WebHook is simple. A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST."

In other words, a WebHook is a method by which your application can react to events that occur during the Subscription Life cycle (e.g. a new subscription, a recurring payment is declined, a subscription is upgraded, etc.).  For example, your blog or iPhone app can use WebHooks to grant customers access to special content, and restrict access to others.

For more information, you can read more at the [[http://wiki.webhooks.org/w/page/13385124/FrontPage|official webhook site]].

===== How it works =====
A WebHook URL is saved in your Merchant Settings.  The URL points to a script in your app.  We send a form POST message to your script when there is an event (e.g. a sign-up). Your script uses the information in the POST to trigger an action (e.g. enable content to a new user). 

A [[merchant_guide:notifications_list_callbackurl|full list of events]] and sample scripts are available.

===== WebHook URL =====

The WebHook URL, which is set in the [[merchant_guide:notifications|Notification Settings]] area of the Merchant Center (separately for each //store//), defines the location of script on your Web site or App that contains code designed by you to interpret and react to the information provided by SubscriptionBridge in the //post-back message//.

Here the steps required to configure your Webhook URL:
  - Log into the [[https://www.subscriptionbridge.com/merchantcenter/login.asp|Merchant Center]].
  - Navigate to "Notification Settings"
  - Under "Advanced Settings" find "Post-back / Webhook URL"
  - Type your URL into the box. We recommend using a secure URL.
  - Click "Save Notification Settings" at the bottom of the page.

===== Webhook Script =====

Unlike Post-backs, a Webhook POST can be received without any complex parsing.

Since the Webhook is a form POST you can retrieve the values the same way you would with any other form on your web site.

===== WebHook POST Fields =====

^ Name ^ Example ^ 
| Amount | 44.98 | 
| BillAddress | 55 Main St. | 
| BillAddress2 | Suite 500 | 
| BillCity | Cityville | 
| BillCompany | Widget, Inc. | 
| BillCountry | US | 
| BillFirstName | Jane | 
| BillLastName | Doe | 
| BillPhone | 555-555-5555 | 
| BillState | CA | 
| BillZip | 55555 | 
| CustomerID | 0123456789 | 
| DtCreated | 3/7/2013 6:04 AM | 
| Email | no-reply@subscriptionbridge.com | 
| EndDate | 1/1/1900 12:00 AM | 
| EndDateTrial | 4/7/2013 6:04 AM | 
| EventCode | sb_n_4a | 
| FirstName | Jane | 
| Guid | ABC123456789 | 
| LastName | Doe | 
| NextBillingAmount | 39 | 
| NextBillingDate | 6/7/2013 6:04 AM |
| PackageName | Widget 123 - Monthly |
| PlanName | Monthly |
| ProductName | Widget 123 |
| ShipAddress | 55 Main St. | 
| ShipAddress2 | Suite 500 | 
| ShipCity | Cityville | 
| ShipCompany | Widget, Inc. | 
| ShipCountry | US | 
| ShipFirstName | Jane | 
| ShipLastName | Doe | 
| ShipPhone | 555-555-5555 | 
| ShipState | CA | 
| ShipZip | 55555 | 
| SID | my custom field |
| StartDate | 3/7/2013 6:04 AM |
| Status | Active |
| StoreActive | True |
| StoreAddress | 123 South St. |
| StoreEmail | no-reply@subscriptionbridge.com |
| StoreID | 1234 |
| StoreKey | subdomain |
| StoreLocale | en-US |
| StoreTimeZone | -5 |
| TaxAmount | 0 |
| TransactionAmount | 39.00 |
| TransactionCurrency | USD |
| TransactionDtCreated | 5/7/2013 7:30:03 AM |
| TransactionID | ABC1234 |
| TransactionMessageCode | 100 |
| TransactionMessageText | SUCCESS |
| TransactionRefID | ABC0123456789 |
| TransactionResultCode | 100 |
| TransactionType | recurring_payment |


===== Testing WebHooks =====

We recommend that you use a site, such as [[http://postcatcher.in/|PostCatcher]], to collect the WebHooks.