The Orbitera platform provides several customization options for white-label marketplaces.  You are able to customize your white-label marketplace by modifying the background, banner, colors, categories, links, and you can even set up your own vanity URL.

That said, there’s more to a marketplace than the look and feel.  When a customer signs up for an account, or when a subscription occurs, the marketplace often needs to notify other systems, capture additional metadata, or even kick off complex workflows.

These actions are termed account and product “callbacks” and are baked into the Orbitera platform. They can be easily leveraged to customize an Orbitera marketplace workflow.

API Callbacks

There are two types of event-based callbacks.  The first are events that are attached at the Account level.  The events include New Subscription, Product Create, and Product Update.

The second type of callback happens at the product level.  These callbacks are tied to product events which include Subscription Create, Subscription Change, Subscription Cancel, Subscription Trial End, and a manual post-subscription deployment event.

Account Level Callbacks

The account level callbacks are under Settings -> Callbacks in the Orbitera Admin console.  These callbacks can be used for a variety of scenarios such as:

  • When a new customer signs up, send the information to your internal CRM system
  • When a new product is created, kick off a separate workflow to process the binary file added to the product
  • When a product has changed, notify customers if a new version of the binary has been added

To enable these scenarios, you would need to implement a service endpoint that Orbitera would call.  In the callback UI, you would add the endpoint and associate it with the event.

An example of where this may be used is adding a new customer to a CRM database.  Assuming there are several API calls to validate user data and assign customers to appropriate groups, you could create a Cloud Function which is called on the New Customer event.  The function call would pass in customer data and your Cloud Function would validate the information and pass that to your CRM system with all the appropriate settings and information so it’s captured as a customer from your white labeled marketplace.

Product Level Callbacks

Product level callbacks are tied to events that are normally used for product entitlements, provisioning or other actions related to an individual product.  For example, customers who subscribe to a SaaS offering will need their account provisioned after the purchase is complete.  Orbitera enables our partners to tie the subscription event to call an endpoint that can handle all the necessary actions required to onboard the customer.

If customer-defined parameters are required, the API Deployment UI enables you to define the input and will pass that information as part of the rest API call.  There are also system variables such as Product SKU and Product Name that can be used.  A full list of system variables is documented later in this blog post.

These product callbacks can also be used to natively deploy AWS infrastructure via CloudFormation.  The AWS option enables a wizard at the end of the purchase flow to enable customers to select their AWS Account that a CloudFormation deployment will be tied to.

For example, if you had a product that launched a CloudFormation template that deployed an AWS AMI and a load balancer, you would upload your CloudFormation script in the product deployment configuration.  When the subscription flow is complete, the customer would follow a simple wizard to select their AWS Cloud Account and deploy the CloudFormation template using that account.

The product callbacks are available under Deployment Actions in the product details page.

Another feature product callbacks support is chaining of events.  This is useful when there are multiple calls to provision a customer or enable an entitlement.  The endpoints must return JSON which gets parsed and can be mapped to other variables in the Outputs section.  The output can then be used as input in subsequent API calls.

Substitute Variables

There are several variables available for the different event callbacks.  These can be used by adding the value in braces in the input fields, for example:  {ProductSku}.  The variable will be filled in by Orbitera during the API call.

Partners can also add the parameters in the query string.  For example:

https://myserver.com?userName={CustomerName}

The list of available variables is here:

Account Callback Event: Customer Signup

  • CustomerName
  • CustomerEmail
  • CustomerFirstName
  • CustomerLastName
  • CustomerTitle
  • CustomerEmail
  • CustomerPhone
  • CustomerOrganization
  • CustomerAddressStreet
  • CustomerAddressSuite
  • CustomerAddressCity
  • CustomerAddressStateCode
  • CustomerAddressStateName
  • CustomerAddressZip
  • CustomerAddressCountryCode
  • CustomerAddressCountryName

If you defined custom fields for your customers, you can pass those custom fields using {CustomerField:NameOfField}

Account Callback Event: Product Create

  • ProductSku
  • ProductName
  • ProductBinaryUrl

The ProductBinaryUrl variable returns a signed timed URL to a file that was uploaded to the product.  The URL will be accessible for one hour.  The duration is not customizable.

Account Callback Event: Product Update

  • ProductSku
  • ProductName
  • ProductBinaryUrl
  • ProductBinaryFilename

Product Callback for all Events

  • CloudAccountNumber
  • CloudAccountProviderCode
  • ProductId
  • ProductName
  • ProductSku
  • CustomerName
  • CustomerEmail
  • CustomerTitle
  • CustomerEmail
  • CustomerPhone
  • CustomerFirstName
  • CustomerLastName
  • CustomerOrganization
  • CustomerAddressStreet
  • CustomerAddressSuite
  • CustomerAddressCity
  • CustomerAddressStateCode
  • CustomerAddressStateName
  • CustomerAddressZip
  • CustomerAddressCountryCode
  • CustomerAddressCountryName

For Product API callbacks, if the callback type is Amazon Web Services, the following variables can also be used in addition to the product API ones listed above:

  • CloudAccountNumber
  • CloudAccountProviderCode

Also for the Amazon Web Services callback type, the following special input parameters for the CloudFormation script will be replaced with the account or customer specific value, depending on the context of the deployment.

  • orbiteraOrganization
  • orbiteraSubscriptionId
  • orbiteraSubscriptionPlanId
  • orbiteraSubscriptionProductId
  • orbiteraSubscriptionPlanName
  • orbiteraSubscriptionProductName
  • orbiteraSubscriptionDescription
  • orbiteraDeploymentId
  • orbiteraCustomerId
  • orbiteraCustomerName
  • orbiteraCustomerEmail
  • orbiteraCustomerAWSAccount

Partner Walkthrough

Now that we’ve gone through all the details, let’s walk through adding an endpoint to provision a SaaS application sold through a Partner’s white-label marketplace.

Scenario:

Charles has a SaaS offering and created a product tile on his white-label marketplace for “Presentation Enhancer”.  The product will make presentation decks super nice with amazing backgrounds, fonts, and colors.  Charles offers the product on Orbitera as a subscription for $9.99 a month.  Once a customer subscribes, they will get an email from Charles’ company (PresentationEnhancer.com) with more information.

Charles navigates to the Orbitera Admin console and selects his product.  He clicks “Edit” and scrolls to the Deployment Actions section.

Charles clicks Add

Charles wants the subscription to trigger once the purchase is complete so he selects the “Subscription Create” event.

He enters a short description “Provision Customer” and enters his provision URL – https://PresentationEnhancer.com?newCustomer.

Charles leaves the Request Type as Post and the Content Type as Form URL-Encoded as that’s what his endpoint is expecting.

Charles clicks on “Edit API Credentials” and enters the authentication credentials for the API.

Charles then clicks “Add” in the Parameters section.  He needs Orbitera to pass in the Customer Name, Email, and ZipCode.  He uses the substitute variables.

Charles double checks the input information and clicks Save.

Charles sees the Action added to his Deployment Actions list and then clicks Save to save the product.

Charles navigates to this white labeled marketplace, signs in as a test customer and purchases the product.  He confirms the purchase showed up on his end and his system emailed the customer information on how to log into PresentationEnhancer.com.

Summary

As you can see, enabling partners to hook into certain events is an easy and powerful way to extend the capabilities of Orbitera and customize workflows.

Hopefully you’ll be able to leverage the callback mechanism in Orbitera to enhance your own white-label marketplace!