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

    • 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 the company 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, 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 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 (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 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, 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.

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

  • 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:

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

    Note: Webhook expansion must be enabled for the integration to work.

  2. Add a URL endpoint to the webhook you created.

  3. 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.

  4. 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.)

  5. 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:

  1. 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.

  2. In 10Duke SysAdmin, change the name of the corresponding product package to the FastSpring product ID.

    See how to edit product packages in SysAdmin.