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 10Duke Enterprise 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. 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 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.
-
-
For both customer types, an email is sent to the created user, who needs to activate their user account by setting a password.
Data required in the account.created
event:
-
account
: The account ID. -
first
(undercontact
): The user’s first name. -
last
(undercontact
): The user’s last name. -
email
(undercontact
): 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
(undercontact
): The company name.-
For a B2B customer, providing the company name is mandatory. This is set as the organization’s name in 10Duke Enterprise.
-
For a B2C customer, the company name is ignored in 10Duke Enterprise 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 Enterprise 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 thecompany
parameter. -
The user or organization ID in 10Duke Enterprise
Key name:
tendukeLicenseeId
This can be used to identify a user or organization that already exists in 10Duke Enterprise. This may be needed if you have created users or organizations in 10Duke Enterprise before creating the customers in FastSpring (for example, using SysAdmin or with a data migration).
If this is provided, the account data in the event is only used for mapping the user or organization to the FastSpring account in the Integration Service component. No new user or organization is created in 10Duke Enterprise.
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 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, theorder.completed
event triggers the customer creation as well. (The account details are included in theorder.completed
event.)
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 account ID. -
product
(underitems
): The product ID for each product in the event. -
quantity
(underitems
): The number of products purchased (the quantity per product in the event).
In addition, you can include the same custom 10Duke Enterprise 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 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, thesubscription.activated
event triggers the customer creation as well. (The account details are included in thesubscription.activated
event.)
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 licenses become invalid after this, but are not deleted. If an end date 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 Enterprise 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 subscription.charge.completed
event triggers the following actions in 10Duke Enterprise:
-
The existing licenses are updated.
-
If the name of the product package included in the received
subscription.charge.completed
event has changed, 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 is different, or if the licensed items included in the 10Duke Enterprise product package have changed.
Note: When the licenses are granted through the Graph API 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, and the old licenses are deleted. If there were seat reservations for the old licenses, those are also deleted.
(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 totrue
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 an update to the validity of the corresponding licenses in 10Duke Enterprise. The valid until date is set to the current instant (now) making the licenses invalid with immediate effect.
Note: When a registered customer’s subscription ends in FastSpring, and the licenses are granted through the Graph API the
subscription.deactivated
event triggers the deletion of the corresponding licenses in 10Duke Enterprise.
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
-
A
subscription.charge.completed
orsubscription.updated
event must be preceded by a correspondingsubscription.activated
event. Otherwise the charge completion or update event is ignored. -
The integration only supports granting seat-based licenses.
-
With B2B customers’ subscriptions, take into account that if you move granted licenses to other entitlements, charging or updating a subscription’s licenses may affect how the organization’s users and devices can access those licenses in 10Duke Enterprise. See more information on authorizing 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 user or organization in 10Duke Enterprise can be correctly identified. For example, granting licenses to the correct existing organization should rely on acquiring the organization ID, instead of relying on an organization name manually entered by 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. Only select events supported by the integration.
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.