Skip to content
Marketplace Elements

Fulfillment Webhook

By implementing a fulfillment webhook into your SaaS product you can automate the manual processes around subscription management.

Receiving subscription messages from Marketplace Elements

Before you can receive subscription messages to your SaaS API, you need to complete the following task in Marketplace Elements:

  • Enable the API fulfillment process for each Offer that will use the API fulfillment process.
  • Record the Offer Public Key for each offer and use the Offer Public Key in your SaaS product to decrypt and validate requests.

Enabling the API Fulfillment Process

The API fulfillment is scoped to each offer, allowing you to continue using the manual fulfillment type for any offers that you have not implemented an API for. You can change between manual and API fulfillment at any time, however, any manual subscriptions that are still in a pending fulfillment state when you change the fulfillment type to API fulfillment, will not be communicated to your API after the change is made. It is recommended that you manually process any pending fulfillments prior to changing to the API fulfillment process.

The following steps need to be completed to enable the API fulfillment process for each offer:

  1. Use the left navigation bar to navigate to Offers.
  2. Select the name, or arrow to the right of the column, for the offer that you would like to enable the API fulfillment process for.
  3. Select Edit Offer.
  4. Under the heading Subscription Fulfillment Type select the API(automated) option.
  5. Under the Webhook Endpoint heading, enter the URL of your SaaS webhook that Marketplace Elements will send requests to.
  6. Click Update Offer to confirm changes.
  7. Back on the offer details page, record the Offer Public Key shown for use in your SaaS API.

After the API fulfillment is enabled, any new subscriptions or changes to an existing subscription, will be sent to your API. This includes changes to any subscriptions that were created with the manual fulfillment process.

Implementing a Webhook

Requests sent to the fulfillment URL that you have defined for each offer are encrypted with a JWT token. Further information on the JWT token, and examples on how to use it, can be found on the JWT token page.

To facilitate the full lifecycle of a subscription, your SaaS webhooks will need to implement the following actions:

  • CreateAccount
  • TermsUpdate
  • UpdateAccount
  • ChangePlan
  • ChangeQuantity
  • Renew
  • Suspend
  • Unsubscribe
  • Reinstate