Using webhooks

Explore how to use your configured webhook(s).

What triggers a webhook?

We use Django Signals to determine when to send a trigger.

• Django Signals allow us to register a callable to be executed when an event happens (Django or defined events).
• FareHarbor defines our own signals and registers code to be executed when signals are triggered.
• Signals can be tied to an object or object class.
• Use the list below to determine what is considered a trigger or a non-trigger.

Bookings

New bookings

• New booking triggers are tied to object class booking (signal booking completed).
• Examples of triggers:
  • New Booking from online or direct or reseller
  • Rebooking
  • Booking w/ partial payment
  • Add or remove customers
  • Online rebooking
• Non-triggers:
  • Refunds
  • Send reminder
  • Add Payment
  • Save or hold card
  • Edit booking notes
  • Check-in status change
  • Add expense or discount
  • Booking Notes
  • Add booking field
  • Reprice booking
  • Set booking total

Updated bookings

• Updated bookings includes new and updated bookings (anything on the booking object that changes).
• Examples of triggers:
  • New bookings (everything listed in the new bookings section)
  • Booking Notes
  • Add expense or discount
  • Check-in status
  • Set Comments
  • Add booking field
  • Refund
  • Add/remove Customer types on a booking
  • Custom fields added/edited
  • Contact information changes for any and all associated future and completed bookings
  • Reprice booking
  • Custom refund
  • Set booking total
  • Online rebooking
  • Canceled bookings
  • Waiver status updates
  • Waiver signatures
• Non-triggers:
  • Send reminder email or text
  • Issue gift card

Canceled bookings

• Examples of triggers:
  • Canceled booking
• Non-triggers:
  • New Bookings
  • Updated bookings

Bookings + Payments

• This data type covers payment and refund data.
• New bookings, updated bookings, and canceled bookings all trigger based on updates to the following data fields:
  • Contact Name
  • Phone
  • Email
  • Activity
  • Availability
  • Customer Types
  • Custom Fields
  • Subtotal
  • Tax
  • Total
  • Amount paid
• Payment Data included: “payments”: [{ “pk”: 285833, “created_at”: “2023-01-12T09:11:28-0800”, “type”: “card”, “in_store_payment_type”: null, “status”: “succeeded”, “currency”: “usd”, “initial_amount_paid”: 1000, “initial_amount_paid_display”: “10.00”, “amount_paid”: 1000, “amount_paid_display”: “10.00”, “refunds”: []

Items

The following triggers set an API call in motion at the item level:

• Item creation: Triggered when an item is created.
• Item deletion: Triggered when an item is deleted.
• Item listing is updated: Triggered when changes are made any to any of the following data at the item level:
  • Item name
  • Item basic info
    • Item SKU
    • Item location
    • Item headline
    • Item description
    • Item external URL
  • Item health and safety
• Item bookability updates: Triggered when the bookability of an item is updated
  • Item is archived
  • Item is private
  • Item is unlisted
  • Booking restrictions are added
  • Online calendars are updated
  • Online payments are enabled or disabled
• Info & policies: Triggered when updates are saved to this section on the item’s listing (Info & Policies > Notes & Policies or Info & Policies > Advanced).
• Notification updates for changes to notifications.

The image below displays sample JSON results from an API item call:

For further details on what actually changed on the item, the webhook contains the external API URL and the dashboard URL.

• The external_api_url found in the JSON can be used by interested parties to make an additional External API call to the particular item, which will return the most up-to-date item information.
• The dashboard_url found in the JSON can be used to find out what has changed.

Why do webhooks trigger so often?

A webhook will trigger each time an update is finalized. This can result in a webhook being triggered frequently if booking updates are made and saved individually.

When making multiple updates on a booking, we suggest making updates in bulk before pressing Save to reduce the number of times a webhook is triggered.

Invoices & webhooks

Webhooks cannot be used for generating invoices, as booking fees are a separate charge and cannot be invoiced. Alternatively, we recommend relying on built-in Dashboard features to send receipts and manage tax settings. This will help ensure a seamless and accurate billing process for you and your customers. Learn more about invoicing.

Internal-only content. Don't copy and paste to anyone.

Invoices

It is important for clients to remember they aren’t allowed to invoice their clients directly, as booking fees are a separate charge and should be invoiced by FareHarbor. Clients are encouraged to rely on built-in Dashboard features to send receipts and manage tax settings.

See the client-facing text here.

Verifying successful completion of an API request

The status of all bookings API requests are captured in the webhook’s activity log. To view a webhook’s activity log:

1. Navigate to the Settings tab.
2. Select Users & Permissions from the sidebar.
3. Select the user associated with the webhook, then navigate to the Webhooks tab.
4. Select the relevant webhook. The activity log will appear at the bottom of your view, under the webhook’s settings.

A request that has been completed successfully will display a request succeeded message.

A request that did not succeed will display a request failed message, and include additional error details as relevant.