Administration System Integration

If you have your own subscription management system and/or invoicing system, Bizplay offers a number of ways to integrate with that. In this section we describe the main integration mechanisms. In the subsections we'll go through the different stages/processes in a customer lifecycle and describe how to best support this with the specific integration point.

Introduction

The following means of communication with an external administration system are supported:

  1. Webhooks are used to send an update to the external system, when a meaningful subscription-related change happens in Bizplay
  2. External data sources are used to retrieve subscription-related data from the external system
  3. Bizplay API can be called from the external system to update corresponding information in Bizplay

The configurations of the first two integrations can be found in the Integrations section of your reseller environment.

Recommended Systems Architecture

For an external system and Bizplay to communicate seamlessly with one another, it is recommended to use an intermediary system that takes care of the inter-system communication as well as the translations of the different data structures. One option is to use Amazon AWS API Gateway for this.

Webhooks

When a subscription-related change happens in Bizplay, you can use a webhook to send the updated information to the external system, so that Bizplay and your external administration system stay in sync and you can take the appropriate action, like invoicing the customer for the new sitation.

Configuring A Webhook

In the Integrations section, you can add a new webhook. You configure it by filling out the following properties:

Property Explanation
Description A description description of your choice, e.g. "System X integration"
Target URL The URL where a webhook request is sent to. This is described in more detail in the paragraph below.
HTTP method The method used to send the webhook HTTP request. Generally, this will be a POST method.
Actions Select all actions that can happen in Bizplay and that you like your external system to receive an update of. E.g. customer.updated will send the new customer details when the customer details are updated in Bizplay.
Optional notification e-mail address You can actively monitor the webhook triggers sent to your external system, by filling our your e-mail address. It will then send you an e-mail when a webhook trigger is sent as well as when one fails after the set number of three retries. That way you can take manual action, should you find that something went wrong in the webhook delivery.
Only notify me of failures Check this box if you only want to receive an e-mail when a webhook delivery actually fails.
Enabled Use this activate of deactivate the webhook. When inactive, this webhook will not be triggered when a change is made in Bizplay.
Target URL

It might well be that for each type of change, your administration system requires a different URL to be called. In that case, you would create a webhook for each of the "actions" that you like to sync with. For example, the customer.updated action might require a POST request to https://your.system.com/company/123, whereas the subscription.canceled action might requere a POST request to https://your.system.com/package/123/cancel. Since both URLs are quite different, a separate webhook for each of them (one for each specific action) would be necessary.

However, chances are that your administration system needs to receive the data in a different format than Bizplay delivers. In that case it makes sense to place a system inbetween Bizplay and your administration system, which:

  1. exposes a generic API to Bizplay, and
  2. converts the data from the Bizplay format to the format needed for your administration system

Amazon's API Gateway is an example of a system with which this can be acchieved. We are happy to help you set this up.

In this scenario we can create a generic API that matches the exact action names from Bizplay, e.g. customer.updated will use https://intermediate.system.com/customer/updated and subscription.canceled will use https://intermediate.system.com/subscription/canceled. Since the URL matches the action name, we can use the following "variables" in the target URL, which will be replaced by the appropriate data when the webhook is triggered:

  1. {{object}}: refers to the first part of the action name (e.g. customer or subscription)
  2. {{action}}: refers to the second part of the action name (e.g. created or canceled)
  3. {{id}}: refers to the id of the subject of the change

Using these variables, a target URL might then look like this: https://intermediate.system.com/{{object}}/{{action}}/{{id}}.

Webhook Security

To prevent just any system from sending change notification to your administration system, a secret key is sent along with each request in a header with name X-Bizplay-Secret. Each webhook has a unique key. This can be found on the webhook details page. On the receiving end of the webhook request (e.g. in the intermediary system), you need to check if the passed in key is correct before processing the request.

Monitoring Webhooks

On the details page of a webhook, you will also see a list of webhook requests that have been sent, along with their status. The status can either be:

  1. Pending: the request will be sent any second now
  2. Ok: the request was delivered successfully
  3. Retrying: there was an error in the last delivery of this request, but it will be retried in a minute. Bizplay will retry three times.
  4. Error: even after three retries, the webhook request could not be delived successfully. Manual action is needed to make sure that Bizplay and your administration system are in sync regarding this specific subject.

External Data Sources

Currently, Bizplay supports retreival of the following two types of information:

  1. invoices, which gives the customer the ability to access all the invoices in your administration system right from Bizplay
  2. customer details, which enables retrieval of a URL through which the customer can update his payment method

Configuring An External Data Source

In the Integrations section, you can add a new external data source. You configure it by filling out the following properties:

Property Explanation
Description A description description of your choice, e.g. "System X integration"
Target URL The URL where the external data can be retrieved. See the Target URL section in the paragraph above for options how to configure this URL.
HTTP method The method used to send the HTTP request. Generally, this will be a GET method.
Actions Select the actions for which you like to retrieve the external data. These can be invoices.list and customer.get.
Enabled Use this activate of deactivate the external data retrieval.

The Way The Integration Works

In Bizplay, each configured data source actions has a different effect.

Action Handling
invoices.list When this action is configured, your customers will get an Invoices button on their company details page in the subscription summary section. When the user clicks that, the invoices will immediately be retrieved from your administration system and presented in a list, with links to the invoices in your admminstration system. This list is cached for 5 minutes.
customer.get When a customer's Invoicing contact id is changed, the customer data will be retrieved in the background. This might take a minute or two to execute. This currently only extracts the payment link URL. When that is stored, the customer will get a Change/update payment method button on their company details page in the subscription summary section.

Bizplay API

Bizplay exposes a limited API which allows your system to send updates to Bizplay directly. Currently this API is available only for activating a new subscription. You typically call this when you (or your customer) creates a new (paid) subscription in your administration system.

API Security

Our API needs to be called on behalf of a regular Bizplay user; specifically a user with a reseller administrator role. From the user list, click on the user details and you'll the API key associated with that user account. If it's not yet present, you can create one by clicking on the Generate button. A user can only see his own full API key. Other user's keys can only be viewed partly obfuscated. Any request made to the API needs to be made with an Autorization header that starts the BEARER followed by a space and then the API key, e.g. BEARER SdV4iLgAttyK2zytj6Lf3W.