Configuring webhooks

What is Basic access authentication?

Basic access authentication is a method for an HTTP user to provide a username and password when making a request. HTTP basic authentication can be used in a third party’s destination URL.

Prerequisites

For Basic access authentication, you must have the following set up:

• A username
• A password for the authentication

Understanding destination URLs

• All URLs must have their username and password URL encoded. URL encoding converts characters into a format that can be transmitted over the Internet.
• The URL has to be converted into a valid ASCII format.
• URL encoding replaces unsafe characters with a “%”.
• URLs cannot contain spaces. URL encoding normally replaces a space with a plus (+).
• SSL is a requirement for the URL, meaning all URLs must begin with https://.

For example, a destination URL might look like:

• https://mycompany.com/EE5746FDB4054852/fareharbor-webhook/
• https://mycompany.com/fareharbor-webhook/?key=EE5746FDB4054852

The next step is creating a webhook.

1. Open the user’s account, if not already open (Settings > Users & Permissions, then select the user).
2. Select the Webhooks tab. (If the Webhooks tab is not visible, please reach out to FareHarbor Support for assistance.)
3. Click the + Add webhook button to set up and create the webhook.
4. Enter a name for the webhook in the Webhook name text field.
5. Select a webhook schema option from the Webhook schema dropdown. Depending upon which schema is selected, the webhook can be set up to return pre-configured or custom data results. Please see the Configuring data types and triggers section for additional information about webhook schema options.

6. Enter a URL in the Webhook URL text field. The client must obtain the webhook URL from the third party and then provide the URL to FareHarbor. Once the webhook has been created, FareHarbor will process and send data to this external software URL.

   (Note: The URL must begin with https://.)

   

7. If you are creating a booking type webhook, select one or more triggers for the webhook. Please see the Configuring data types and triggers section for additional information about trigger options.

   At least one trigger must be selected before a pre-configured or custom booking webhook can be created. Triggers are not needed to create an item webhook.

8. Click the Create button.

The webhook setup consists of two additional variables:

• The data type that you want to send to the webhook
• The trigger that will launch the process

Data types: Bookings

There are five booking data types included in the Webhook schema dropdown that can be sent to a webhook:

• Bookings only: The default setting. The data fields returned from a booking include:

  Contact Name, Phone, Email, Activity, Availability, Customer Types, Custom Fields, Subtotal, Tax, Total, Amount paid

  Please note that payment and refund information is not included with this data type.

• Bookings only (Optimized): Compared to Bookings only, this data type returns a smaller group of fields. Using Bookings only (Optimized) can help improve performance and return the data that is of most importance to you. Note that these fields do not include payment or refund information.

  The following data fields are returned using this data type:

  Contact Name, Phone, Email, Activity, Availability, Customer Types, Custom Fields, Subtotal, Tax, Total, Amount paid

• Bookings + payments: If you want to send payment and refund data in addition to what is sent with Bookings only, select this type for all bookings fields and including payment information.

• Bookings + payments (Optimized): Use this data type when you want to receive a subset of bookings data, as compared to the full Bookings + payments output. The data returned for the optimized call will also include payment and refund information. Sending data using an optimized connection can enhance server performance during the API call by filtering out only the most frequently used fields. This will also allow you to more effectively manage only the data that is of interest.

• Create custom booking schema: This data type allows you to customize what specific booking data will be included.

  Custom booking schemas cannot be updated. Create a new custom booking webhook schema to implement an updated setup. If the updated schema will use the same destination URL, deleting the old schema can prevent receiving duplicate data.

  

  Click the Show recent booking data option to view examples of recently-populated field data.

  Note: Booking data changes will not be saved until the Save changes button is clicked.

  Please see FareHarbor’s API documentation if more technical webhook details are needed.

Data types: Items

Select the Items option from the Webhook schema dropdown to send item data.

Triggers

A trigger is the event in FareHarbor that determines when information is sent to the webhook URL. Examples are when a booking or item is updated, canceled or created.

There are several trigger options from which to select. To specify the trigger for the data transfer:

1. Ensure you have selected the desired data type.
2. Select one of the following triggers:
   • New bookings: The workflow will only activate when a new booking is created.
   • Updated bookings: The workflow will only activate when a pre-existing booking is updated. It will send all information, including new bookings and updates to existing bookings (cancellations, etc.).
   • Canceled bookings: The workflow will only activate when a booking is canceled.

Once the webhook has been finalized and saved, details under the Webhook tab will look like this:

You can update a webhook’s triggers at any time by clicking the Edit option.

Please reach out to FareHarbor Support if you’d like to review webhook activity log data. When making a request, please provide us with the following details for each relevant webhook:

• Webhook name
• Date (or date range) of requested activity data