Connect to FastSpring

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

10Duke Enterprise supports the use of webhooks to trigger actions in 10Duke Enterprise 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 the 10Duke Integration Support team 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 Enterprise end, which are handled by the 10Duke Integration Support team. This includes enabling the Integration Service component for your deployment, and defining the connection between the component and FastSpring as an OAuth client application, which you will see in the 10Duke SysAdmin tool.

Supported webhook events and actions

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

The FastSpring events sent to 10Duke Enterprise must include certain data required by the integration.

account.created

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

For a B2C customer, this creates a user account.
For a B2B customer, this creates:
- A new organization in 10Duke Enterprise.
- A user account for the organization’s first administrator, with access to the 10Duke OrgAdmin tool (if you’re providing it for your B2B customers).
- A default entitlement to hold the organization’s licenses.
- An “employees” user group where the first administrator user is added, and which is granted access to the default entitlement.

See more information on user accounts and organizations.

Data required in the account.created event:

account: The customer ID.
first (under contact): The user’s first name.
last (under contact): The user’s last name.
email (under contact): The user’s email address.

This is set as the email address in the 10Duke Enterprise user account. The email address must be unique across users in 10Duke Enterprise.
company (under contact): The company name.
- If a company name is provided, 10Duke Enterprise handles the account as a B2B customer, and sets the company name as the organization’s name.
- If not provided, the account is handled as a B2C customer.

See detailed information on the account.created event in FastSpring’s documentation.

order.completed

When a one-time order is created for a new or registered customer in FastSpring, the order.completed event triggers the following actions in 10Duke Enterprise:

New licenses are granted to the customer (a B2C user or a B2B organization).

The event specifies one or more FastSpring products, which map to 10Duke Enterprise product packages that are used for granting the licenses.
For a B2C customer, granting licenses also automatically creates an entitlement if they don’t have one yet.
For a B2B customer, the licenses are always created in the organization’s default entitlement.
If the account.created event is not sent for a new customer, this event triggers the customer creation as well.

See more information on granting licenses.

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

Data required in the order.completed event:

order: The order ID.
account: The customer 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).

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 following actions in 10Duke Enterprise:

New licenses are granted to the customer (a B2C user or a B2B organization).

The event specifies one FastSpring product, which maps to a 10Duke Enterprise product package that is used for granting the licenses.

If the FastSpring subscription contains multiple products, they are included in the subscription’s order.completed event.
For a B2C customer, granting licenses also automatically creates an entitlement if they don’t have one yet.
For a B2B customer, the licenses are always created in the organization’s default entitlement.
If the account.created event is not sent for a new customer, this event triggers the customer creation as well.

See more information on granting licenses.

Data required in the subscription.activated event:

subscription: The subscription ID.
beginInSeconds: The subscription validity start date.

If a start date is not provided, the licenses are valid immediately.
nextInSeconds: The subscription validity end date.
- The license becomes invalid after this date, but is not deleted.
- If an end date is not provided, the licenses are valid indefinitely.
account: The customer ID.
product: The product ID of the product.
quantity: The number of products purchased.

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 subscription.charge.completed event triggers the following actions in 10Duke Enterprise:

New licenses are granted to the customer (a B2C user or a B2B organization) that are valid until the end of the new subscription period.

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

This may result in a different set of licenses than at the time of the subscription activation. This may happen if the FastSpring product specified in the event are different, or if the licensed items included in the 10Duke Enterprise product package have changed.
The old licenses are deleted.

See more information on updating licenses.

(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 Enterprise.

See more information on deleting user licenses or organization licenses.

Data required in the subscription.deactivated event:

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

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

Limitations

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.
The integration only supports granting seat-based 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.

Setup in FastSpring

Complete the steps below for the integration setup in FastSpring.

After all the setup steps have been completed, the 10Duke Integration Support team can enable the integration in 10Duke Enterprise.

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 Enterprise, and creating a hash-based message authentication code (HMAC) secret for the webhook which you need to provide to the 10Duke Integration Support team.

Before you start:

You need the base URL of the 10Duke Enterprise integration service where the webhook will send the events. Contact the 10Duke Integration Support team 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 10Duke Enterprise deployment’s base URL.
Next, create an HMAC SHA256 secret.

10Duke Enterprise 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. See information on the supported events.

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

Provide the webhook HMAC secret to the 10Duke Integration Support team. 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 the 10Duke Integration Support team with the new secret in time to keep the integration working.

Step 2: Map products in FastSpring and 10Duke Enterprise

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

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

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 Enterprise product packages.

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 10Duke SysAdmin, change the name of the corresponding product package to the FastSpring product ID.

See how to edit product packages in SysAdmin.