developer_guide:developer_guide:webhooks

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 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 full list of events and sample scripts are available.

WebHook URL

The WebHook URL, which is set in the 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:

  1. Log into the Merchant Center.
  2. Navigate to “Notification Settings”
  3. Under “Advanced Settings” find “Post-back / Webhook URL
  4. Type your URL into the box. We recommend using a secure URL.
  5. 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 PostCatcher, to collect the WebHooks.

developer_guide/developer_guide/webhooks.txt · Last modified: 2013/05/07 10:33 by matt