How to build a digital waiver plugin?

Xola allows digital waiver solutions to deeply integrate with it via the Xola App Store infrastructure. This article details how to build a plugin which can interface between Xola and your waiver system.

Prerequisites

To get started you must have a Developer Account. You'll need the API key from this account when registering your plugin.
Please ensure your waiver system publishes webhooks whenever a waiver is signed on your system.

Implementation

To build a waiver plugin, you'll need to build a web service that implements the following:

1. Endpoint to receive webhooks for plugin install and uninstall events

Your web-service will be notified whenever a user installs/uninstalls your plugin through webhooks. You will need an endpoint to receive these webhooks.

Plugin install

Two fields are present in the webhook payload:

eventName, which will equal 'installation.create'
data, which will contain the Installation object. Relevant fields from the data
would be:

seller: This contains the unique ID of the Xola seller that the plugin was installed for.
config: When registering the plugin, you can setup a list of fields which you require from the user to setup the integration (see the Plugin Registration section for more details). The config field will be an array of key-value pairs, corresponding to these fields setup during plugin registration.

{
  "eventName": "installation.create",
  "data": {
    "id": "<installation_id>",
    "plugin": "<plugin_id>",
    "seller": "<seller_id>",
    "config": {
      "plugin_config_1": "xxxxxx",
      "plugin_config_2": "yyyyy"
    },
    "updatedAt": "<ISO 8601 timestamp>"
  }
}

Plugin uninstall

Similar to plugin install, two fields are present in the webhook payload,

eventName which will equal 'installation.delete'
data which will contain the Installation object.

You would need to do a few things when an account uninstalls your plugin:

De-register on waiver system: Make sure you delete the webhooks and/or configuration specific to your integration that is saved on the waiver system.
Unlink experiences linked to your waiver plugin: Experiences on Xola will contain waiver related configuration in a field called waiverPreference. On uninstall, you'll need to delete the waiverPreference for all experiences which are linked to your plugin. This will ensure that new booking emails sent for these experiences no longer link to your waiver system for signing waivers.

For experiences linked to your plugin, the waiverPreference.remoteSystem field will be equal to the unique ID of the your plugin user (see the Plugin Registration section to see how to obtain this).
You can first all fetch all experiences which have a waiverPreference linked to your remote system using this API:

GET https://sandbox.xola.com/api/experiences?seller=SELLER_ID&waiverPreference_remoteSystem=<plugin_user_id>

🚧
Authentication
You'll need to be authenticated with your plugin user's API key to use the above API. (see the Plugin Registration section to see how to obtain this)

To delete waiver preference for a given experience, you can use the following API. You will be only authorized to delete waiver preferences for experiences linked to your plugin.

DELETE https://sandbox.xola.com/api/experiences/EXPERIENCE_ID/waiver

🚧
Authentication
You'll need to be authenticated with your plugin user's API key to use the above API. (see the Plugin Registration section to see how to obtain this)

2. Notify Xola of the newly signed waiver

Once the customer has signed a waiver on your system, you'll need to notify Xola with the details of the signed waiver. To create a waiver on Xola, use the following API:

POST https://sandbox.xola.com/api/waivers

🚧
Authentication
You'll need to be authenticated with your plugin user's API key to use the above API. (see the Plugin Registration section to see how to obtain this

📘
Version Header Required
In your headers for this request, please make sure you have ‘x-api-version’ set to ‘2018-09-14’ or greater.

This API accepts the following fields:

Field	Description	Type	Required
`remoteId`	The unique ID of the waiver on the waiver system	string	Yes
`remoteSystem`	This should equal the unique ID of the Xola user associated with your plugin. You can obtain this ID when you register your plugin.	string	Yes
`waiverTypeId`	The unique ID from the waiver system for the template for this waiver	string	Yes
`customerEmail`	The primary email for the waiver	string	Yes
`seller`	This field should contain a key `id` whose value should equal the unique ID of the Xola seller you're creating the waiver for	object	Yes
`signedAt`	ISO 8601 date string indicating the date and time at which the waiver was signed	string	Yes
`url`	URL from which to fetch a PDF file for the signed waiver. You can either directly link to the waiver system if it provides a link to the PDF file, or implement an endpoint in your plugin	string	Yes
`tags`	An array of strings containing any optional metadata. Include the Xola order's short code in here to automatically link this waiver to the Xola order.	array	No
`participants`	an array of Participant objects indicating the people who are included in this waiver. The Participant object supports the following fields: `dateOfBirth`: indicates the date of birth represented as a string in 'YYYY-MM-DD' format `customerName`: string value which should include the participant's full name. `customerEmail`: string value containing participant's email address `phone`: string value containing participant's phone number	array	Yes

{
  "remoteId": "56dgsumqh",
  "remoteSystem": "5b6034a251739c6f0d1bb90e",
  "waiverTypeId": "58gaqumah",
  "customerEmail": "[email protected]",
  "signedAt": "2018-08-30T05:27:53.597Z",
  "seller": {"id": "54ccb8802c32195c90b7acd9"},
  "tags": ["Zipline", "skqud"],
  "url": "https://waiver.plugin.example.com/waivers/56dgsumqh/url?user=5b878057a48cf2730c8b456f",
  "participants": [
    {
      "customerName": "John Doe",
      "customerEmail": "[email protected]",
      "dateOfBirth": "1927-06-16",
      "phone": "555-555-5555"
    },
    {
      "customerName": "Jane Doe",
      "customerEmail": "[email protected]",
      "dateOfBirth": "1977-04-16"
    }
  ]
}

3. Fetch waiver templates

This endpoint should fetch all active waiver templates from the waiver system for a particular user and return the sign waiver form urls for each of them. Xola will use the response from this endpoint to allow users to link Xola experiences to specific templates from your waiver system. A query param called user will be used in the request to indicate which Xola user the request is being made for. This is the endpoint whose url is used for the abilities.waiver.templatesUrl field when registering your plugin.

Your response should contain a field called data which should in turn contain an array of WaiverTemplate objects. Here is the structure for the WaiverTemplate object:

Field	Description	Type	Required
`id`	Unique ID of the template on the waiver system	string	Yes
`name`	The name of the template on the waiver system	string	Yes
`url`	The url to the web form for this waiver template. On Xola, this url will be included in the confirmation emails and post booking screens to link to the sign waiver form	string	Yes
`parameterizedUrl`	In the sign waiver link sent to the customers, if you wish to use fields from the created order on Xola to include details like customer name, you can provide a Twig template for doing so. If your Twig template is invalid/fails to render, the sign waiver link will fall back to the value provided in the `url` field.	string	No

{
  "data": [
    {
      "id": "58gaqumah",
      "name": "Zipline Waiver",
      "url": "https://www.waiver.system.example.com/w/58gaqumah/web",
      "parameterizedUrl":
      "https://www.waiver.system.example.com/58gaqumah/web?autofillFirstName={{ order.customerFirstName }}&autofillLastName={{order.customerLastName }}&autofillTag={{item.shortCode}}"
    },
    {
      "id": "58ghism9",
      "name": "3 Hour Swim Waiver",
      "url": "https://www.waiver.system.example.com/w/58ghism9/web",
      "parameterizedUrl":
      "https://www.waiver.system.example.com/w/58ghism9/web?autofillFirstName={{ order.customerFirstName }}&autofillLastName={{order.customerLastName }}&autofillTag={{order.id}}"
    }
  ]
}

Plugin Registration

To register your plugin, use the following API:

POST https://elrond.sandbox.xola.com/plugins

🚧
Authentication
You'll need to authenticate with the API key of your developer account for this API. This would be the API key of the Xola account from the Prerequisites section.

This API accepts the following fields:

Field	Description	Type	Required
`name`	Name of your plugin	string	Yes
`description`	A brief description of your plugin. Should be one paragraph formatted in Markdown!	string	Yes
`summary`	A brief summary for your plugin. Should be one sentence.	string	Yes
`prerequisites`	A list of string values detailing any prerequisites for installing your plugin	array	No
`tags`	An array of tags for your plugin. These will be searchable on the Xola Appstore	array	No
`config`	This can be used to configure a list of fields you need from the user when they are installing your plugin. Each element from the config field will be displayed as a separate section of forms fields to the user. This supports two fields: `title`: A title for each config section (optional) `fields`: An array of fields you require from the user. Each element in this array should contain: - `type`: A string value indicating the type of the field. Currently only "text" is supported. - `name`: A string value indicating the under which to receive this field on your web service when a user installs your plugin. - `label`: A string value indicating the label to be used for this form field when displayed to the user - `required`: A boolean value indicating if this field is required. If this field is not present, then the installation will fail for the user	array	No
`permissions`	an array of strings representing the permissions your plugin requires on Xola	array[enum]	No
`webhooks`	If you wish to listen to specific events on Xola through webhooks, you should register for them through this field. The webhooks field supports the following fields: url: This is the url on your plugin web service where you will be listening to all webhooks from Xola. events: This should be an array on events from Xola that your plugin wishes to register for.	object	No
`abilities`	Plugins of different types can use this field to implement specific functionality. See the Configuring waiver type plugins to see how to setup this field for a waiver plugin	object	No

Every plugin on Xola is associated with a unique user, whose details are included in the response from the above API in a field called user. This field contains:

id: The unique ID of this user on Xola. We will use this unique ID to identify all waivers and experiences on Xola that are linked to your waiver system.
apiKey: The API key for this user. All calls to Xola from your plugin should be authenticated with this API key.

Configuring waiver type plugins

This section details what to set for a few specific fields to configure a waiver plugin:

permissions: Your plugin should request for "ROLE_DIGITAL_WAIVER" to ensure that it has the ability to update waiver URLs in Xola experiences.
config: Any configuration you need from a user when they are installing your plugin will need to be included here. Typically, this would be authentication credentials for the waiver system plus any additional data you might need to configure webhooks on waiver sign on the waiver system.
webhooks: You'll typically want to include 'installation.create' and 'installation.delete' in the webhooks.events field for this. The url should be the link where you want these webhooks to be published. See the Endpoint to receive webhooks for plugin install and uninstall events section below for more details.
abilities: To be recognized as a waiver plugin, you will need to include the 'waiver' ability. The 'waiver' ability will have to provide a templatesUrl field whose value will be the URL from where Xola can fetch waiver templates configured for a particular user. See Fetch Waiver Templates section below for more details.

{
  "name": "Smartwaiver",
  "config": [
    {
      "title": "Smartwaiver V4 API Key",
      "summary": "Use Smartwaiver's Digital Waivers",
      "description": "Integrate Smartwaiver with Xola\\nShow waivers from Smartwaiver on Xola",
      "prerequisites": [
        "An account with Smartwaiver is required in order to use this integration. This integration is available to all pricing plans."
    ],
      "fields": [
        {
          "type": "text",
          "name": "smart_waiver_api_key",
          "label": "Smartwaiver V4 API Key",
          "required": true
        }
      ]
    }
  ],
  "tags": [
        "waiver",
        "smartwaiver",
        "e-waiver"
    ],
  "permissions": [
    "ROLE_DIGITAL_WAIVER"
  ],
  "webhooks": {
    "url": "https://waiver.plugin.example.com/appStore/webhooks",
    "events": [
      "installation.create",
      "installation.delete"
    ]
  },
  "abilities": {
    "waiver": {
      "templatesUrl": "https://waiver.plugin.example.com/templates"
    }
  }
}

{
  "id": "5b994721d4abec2a201d79ae",
  "name": "Smartwaiver",
  "config": [
    {
      "title": "Smartwaiver V4 API Key",
      "summary": "Use Smartwaiver's Digital Waivers",
      "description": "Integrate Smartwaiver with Xola\\nShow waivers from Smartwaiver on Xola",
      "prerequisites": [
        "An account with Smartwaiver is required in order to use this integration. This integration is available to all pricing plans."
    ],
      "fields": [
        {
          "type": "text",
          "name": "smart_waiver_api_key",
          "label": "Smartwaiver V4 API Key",
          "required": true
        }
      ]
    }
  ],
  "tags": [
        "waiver",
        "smartwaiver",
        "e-waiver"
    ],
  "permissions": [
    "ROLE_DIGITAL_WAIVER"
  ],
  "webhooks": {
    "url": "https://waiver.plugin.example.com/appStore/webhooks",
    "events": [
      "installation.create",
      "installation.delete"
    ]
  },
  "abilities": {
    "waiver": {
      "templatesUrl": "https://waiver.plugin.example.com/templates"
    }
  },
    "user": {
        "id": "5b994720a48cf26f048b4567",
        "apiKey": "hCe32gqRMWEHemyTQVFwtyvNWqy5tJhsa0mqA63aiZw"
    }
}

How to build a digital waiver plugin?

Prerequisites

Implementation

1. Endpoint to receive webhooks for plugin install and uninstall events

Plugin install

Plugin uninstall

🚧
Authentication

🚧
Authentication

2. Notify Xola of the newly signed waiver

🚧
Authentication

📘
Version Header Required

3. Fetch waiver templates

Plugin Registration

🚧
Authentication

Configuring waiver type plugins

Prerequisites

Implementation

1. Endpoint to receive webhooks for plugin install and uninstall events

Plugin install

Plugin uninstall

🚧Authentication

🚧Authentication

2. Notify Xola of the newly signed waiver

🚧Authentication

📘Version Header Required

3. Fetch waiver templates

Plugin Registration

🚧Authentication

Configuring waiver type plugins

🚧
Authentication

🚧
Authentication

🚧
Authentication

📘
Version Header Required

🚧
Authentication