Connect to FastSpring

This article provides instructions on the steps required from you (the vendor), when you’re integrating 10Duke Scale with FastSpring using webhooks.

10Duke Scale supports the use of webhooks to trigger actions in 10Duke Scale based on FastSpring events to:

Set up your B2B and B2C customers
Grant licenses for one-time orders
Grant and update licenses for subscriptions
Delete licenses when a subscription ends

The integration requires an optional 10Duke Integration Service component that is purchased separately.

Contact 10Duke to get started with the integration, and get support with the setup steps if needed.

The integration also requires setup and configurations at the 10Duke Scale end, which are handled by 10Duke.

Supported webhook events and actions

You can use webhooks in FastSpring for the following events to trigger actions in 10Duke Scale.

The FastSpring events sent to 10Duke Scale must include certain data required by the integration. There’s also some optional data that can be included.

account.created

When an e-commerce account is created for a customer in FastSpring, the account.created event triggers the following actions in 10Duke Scale:

A customer is created, and a default license container to hold the customer’s licenses.
For a B2C customer, this also creates a license consumer of type person. (Note that currently the integration only supports key-based licenses, which are consumed using a license key.)

See more information on customers, license containers, and license consumers in 10Duke Scale.

Data required in the account.created event:

account: The account ID.
first and last (under contact): The customer’s first and last name.

These combined are set as the (formal) name for a B2C customer and the associated license consumer, and also as the display name for the customer. (The values are not used for B2B customers.)
email (under contact): The customer’s email address.

This is set as the email address of the customer in 10Duke Scale, and of the B2C customer’s license consumer. The email address must be unique across customers and license consumers in 10Duke Scale.
company (under contact): The company name.
- For a B2B customer, providing the company name is mandatory. This is set as the B2B customer’s formal name and display name in 10Duke Scale.
- For a B2C customer, the company name is ignored in 10Duke Scale if provided.
If the event doesn’t specify the customer type in the optional tags parameter (see below), company is used to determine this: if a company name is provided, the account is handled as a B2B customer, and otherwise as a B2C customer.

In addition, you can include the following custom 10Duke Scale data as key-value pairs using the tags parameter:

The customer type (a B2C or a B2B customer).

Key name: tendukeLicenseeType

Possible values: PERSONAL (default), ORGANIZATION

If this is set to ORGANIZATION, a company name must be provided in the company parameter.
The customer ID in 10Duke Scale

Key name: tendukeLicenseeId

This can be used to identify a customer that already exists in 10Duke Scale. This may be needed if you have created customers in 10Duke Scale before creating the accounts in FastSpring (for example, using the 10Duke Scale UI console or with a data migration).

If this is provided, the account data in the event is only used for mapping the 10Duke Scale customer to the FastSpring account in the Integration Service component. No new customer is created in 10Duke Scale.

See detailed information on the account.created event in FastSpring’s documentation. See also an example of how to include the tags parameter in an event.

order.completed

When a one-time order is created for a new or registered customer in FastSpring, the order.completed event triggers the issuing of new licenses to the B2C or B2B customer in their default license container.

The event specifies one or more FastSpring products, which map to 10Duke Scale product configurations that are used for issuing the licenses.

Note: A license key is generated for each license, which also automatically creates corresponding license consumers of type license key. Each license can only be consumed using its license key.

See more information on issuing licenses in 10Duke Scale.

If the account.created event is not sent for a new customer, the order.completed event triggers the customer creation as well. (The account details are included in the order.completed event.)

The order.completed event is also sent at subscription creation in FastSpring, but 10Duke Scale only uses the event’s data for one-time orders.

Data required in the order.completed event:

order: The order ID.
account: The account ID.
product (under items): The product ID for each product in the event.
quantity (under items): The number of products purchased (the quantity per product in the event).

In addition, you can include the same custom 10Duke Scale data tendukeLicenseeType and tendukeLicenseeId using the tags parameter as in the account.created event.

See detailed information on the order.completed event in FastSpring’s documentation.

subscription.activated

When a subscription to a product is created for a new or registered customer in FastSpring, the subscription.activated event triggers the issuing of new licenses to the B2C or B2B customer in their default license container.

The event specifies one FastSpring product, which maps to a 10Duke Scale product configuration that is used for issuing the licenses.

Note: A license key is generated for each license, which also automatically creates corresponding license consumers of type license key. Each license can only be consumed using its license key.

See more information on issuing licenses in 10Duke Scale.

If the account.created event is not sent for a new customer, the subscription.activated event triggers the customer creation as well. (The account details are included in the subscription.activated event.)

Data required in the subscription.activated event:

subscription: The subscription ID.
beginInSeconds: The subscription validity start date and time (interpreted as UTC time in 10Duke Scale).

If a start date and time is not provided, the licenses are valid immediately.
nextInSeconds: The subscription validity end date and time (interpreted as UTC time in 10Duke Scale).

The licenses become invalid after this, but are not deleted. If an end date and time is not provided, the licenses are valid indefinitely.
account: The account ID.
product: The product ID of the product.
quantity: The number of products purchased.

In addition, you can include the same custom 10Duke Scale data tendukeLicenseeType and tendukeLicenseeId using the tags parameter as in the account.created event.

See detailed information on the subscription.activated event in FastSpring’s documentation.

subscription.charge.completed

When a registered customer’s subscription has been charged in FastSpring, the actions triggered by the subscription.charge.completed event depend on what type of changes were made to the subscription in FastSpring.

If only the subscription validity is changed (for example, the subscription is renewed by extending the validity end date), this triggers an update of the validity of the associated licenses in 10Duke Scale.

However, if any other changes are made to the subscription (for example, there’s a change in what products the subscription includes, or the quantity of a product changes), this triggers the following actions in 10Duke Scale:

New licenses are issued to the B2C or B2B customer that are valid until the end of the new subscription period.

Like with subscription.activated, this event specifies the product to be used for issuing the licenses.

This may result in a different set of licenses than at the time of the subscription creation, if the FastSpring product specified in the event is different.
The old licenses are deleted.

If the old licenses had license keys, those are also deleted with the licenses. New license keys are generated for the new licenses, and they can only be consumed using the new license keys. The old license keys are no longer valid.

(The subscription.charge.completed event is not sent when the subscription is first created, only subscription.activated is sent.)

Data required in the subscription.charge.completed event:

The same fields as in the subscription.activated event.
active: Must be set to true or the event is ignored.

Note: To avoid a break in the license validity when replacing a customer’s existing licenses, the date from beginInSeconds is only used for the new licenses if it’s in the past. If the date is in the future or no date is provided, the license validity start is set to the current date.

See detailed information on the subscription.charge.completed event in FastSpring’s documentation.

subscription.updated

When a registered customer’s subscription has been updated in FastSpring, the subscription.updated event triggers the same actions as the subscription.charge.completed event.

Data required in the subscription.updated event:

The same fields as in the subscription.activated event.
active: Must be set to true or the event is ignored.

Note: To avoid a break in the license validity when replacing a customer’s existing licenses, the date from beginInSeconds is only used for the new licenses if it’s in the past. If the date is in the future or no date is provided, the license validity start is set to the current date.

See detailed information on the subscription.updated event in FastSpring’s documentation.

subscription.deactivated

When a registered customer’s subscription ends in FastSpring, the subscription.deactivated event triggers the deletion of the corresponding licenses in 10Duke Scale.

See more information on deleting licenses in 10Duke Scale.

Data required in the subscription.deactivated event:

subscription: The subscription ID.
account: The account ID.

See detailed information on the subscription.deactivated event in FastSpring’s documentation.

Limitations

The integration requires predefined products for issuing licenses. Feature licenses are not supported.
The integration only supports granting seat-based licenses.
The integration only supports issuing licenses that have a license key. This means the licenses can only be consumed using their associated license key.
The integration doesn’t support issuing licenses restricted to certain client application versions.
A subscription.charge.completed or subscription.updated event must be preceded by a corresponding subscription.activated event. Otherwise the charge completion or update event is ignored.
With B2B customers’ subscriptions that grant licenses without a license key, take into account that if you move granted licenses to other license containers, charging or updating the FastSpring subscription may affect how license consumers of type person and device can access those licenses in 10Duke Scale. This is because some subscription changes cause the old licenses to be deleted, and the new, updated licenses are created in the customer’s default license container. See more information on managing license consumer access to licenses.

Recommendations for purchase flow

To handle returning customers, we recommend that your FastSpring implementation makes sure that a customer uses their existing FastSpring customer account if they have one. Otherwise there’s a risk that licenses are not granted correctly to the customer.

In addition, make sure that your implementation requests the customer to enter sufficient details at login so that the existing customer in 10Duke Scale can be correctly identified. For example, granting licenses to the correct existing B2B customer should rely on acquiring the customer ID, instead of relying on a company name manually entered by the user.

Setup in FastSpring

Complete the steps below for the integration setup in FastSpring.

Step 1: Create a webhook in FastSpring

In FastSpring, create a new webhook for the integration.

This includes defining the FastSpring events that the webhook will send to 10Duke Scale, and creating a hash-based message authentication code (HMAC) secret for the webhook which you need to provide to 10Duke.

Before you start:

You need the base URL of the 10Duke Scale Integration Service where the webhook will send the events. Contact 10Duke to get the URL.

To create a webhook in FastSpring:

In developer tools, go to webhook configuration and add a new webhook.

Note: Webhook expansion must be enabled for the integration to work.
Add a URL endpoint to the webhook you created.
In the URL endpoint, first define the URL where the webhook sends events.

URL format: <integration_service_base_url>/fastspring/actions/webhook

Note: This base URL is not the same as your API base URL for 10Duke Scale.
Next, create an HMAC SHA256 secret.

10Duke Scale will use the HMAC secret to verify that the event was sent by the correct webhook in FastSpring.
- We recommend that the secret key:
  - Has a minimum of 16 characters.
  - Includes at least one special character, one number, one uppercase letter, and one lowercase letter.
- Copy and store the secret before saving the URL endpoint. (You can also copy it later if needed.)
Select the events that are sent to this URL endpoint. Only select events supported by the integration.

See detailed information on FastSpring webhooks in FastSpring’s documentation.

Provide the webhook HMAC secret to 10Duke. Make sure to use a secure method to communicate this, such as GNU Privacy Guard (GPG) encryption.

Note: If you’re rolling your FastSpring webhook secrets periodically, make sure you always provide 10Duke with the new secret in time to keep the integration working.

Step 2: Map products in FastSpring and 10Duke Scale

To enable the integration to manage licenses to your products correctly, map the products defined in your FastSpring system to the product configurations defined in 10Duke Scale.

The mapping is based on setting the product’s unique product ID from FastSpring as the product configuration’s name in 10Duke Scale.

Note: Only map FastSpring products of type “product” (one-time purchases) and “subscription”. If you use the product type “bundle”, do not map those to 10Duke Scale product configurations.

To map a product:

On FastSpring’s product list, open the product or subscription, and copy the product ID from the product path field.

See detailed information on managing FastSpring products in FastSpring’s documentation.
In the 10Duke Scale UI console, change the technical name of the corresponding product configuration to the FastSpring product ID.

See how to edit product configurations in the UI console.

Step 3: Set up API authorization keys for Integration Service

As the last step, set up API keys for authorizing the Integration Service component to connect to the 10Duke Scale APIs: store the public API key in 10Duke Scale and provide the corresponding private key to 10Duke.

We recommend that you generate a new API key pair for the integration.

When storing the public API key in the UI console, note the following:

In Default key use, select Verify Scale JWT.
In Key ID, we recommend that you use a value that makes it easy to later identify where this API key is used. You could, for example, include a prefix such as “fastspring-integration” in front of the ID.

Provide the private key from the key pair to 10Duke. Make sure to use a secure method to communicate it, such as GNU Privacy Guard (GPG) encryption.

After all the setup steps have been completed, 10Duke can enable the integration in 10Duke Scale.