Webhooks

Introduction

Webhooks allow external services to be notified by iGMS when certain events happen. When a specified event happens, we send a POST request to the URL you've provided. To register a webhook you should email us to support@igms.com and provide the following information:

• Client ID of your iGMS API Application
• Webhook type (Calendar data change, Booking change, Guest data change, or Properties change)
• a URL (or URLs) to send requests to. You may provide different URLs for different types of webhooks

Webhooks general info

Every webhook request will have the following body schema:

Key	Type	Description
type	string	Webhook type. One of booking_data, calendar_data, guest_data, properties_data
data	object[]	Array of webhook data objects

The schema of objects in the data field depends on the webhook type. The response to the webhook request must be 200 OK, other codes would trigger a series of retries with exponential backoff.

List of webhooks

Name	Description
Booking change	Notify about reservation change
Calendar data change	Notify about calendar data change
Guest data change	Notify about guest details change
Properties change	Notify about created\deleted properties
Property calendar control change	Notify about enabling/disabling pricing management app for property
Connection revoked	Notify about revoking connection

Booking change

This webhook is sent when a booking is changed. For this webhook data objects will be in the following format:

Key	Type	Description
company_uid	string	UID of company
booking_uid	string	UID of booking
reservation_code	string	Reservation code
booking_status	string	One of available booking statuses (see the corresponding filters section)
platform_type	string	One of available platform types (see the corresponding filters section)
listing_uid	string	UID of booked listing
property_uid	string	UID of booked property
guest_uid	string	UID of guest
host_uid	string	UID of host
number_of_guests	int	Number of guests
price	object	Pricing data object
local_checkin_dttm	string	Local checkin datetime in Y-m-d H:i:s format
local_checkout_dttm	string	Local checkout datetime in Y-m-d H:i:s format
created_dttm	string	Creation datetime in Y-m-d H:i:s format
updated_dttm	string	Last update datetime in Y-m-d H:i:s format

Pricing data

Key	Type	Description
currency	string	Currency code (3 symbols)
price_base	string	Numeric string with fraction
price_extras	string	Numeric string with fraction
price_fee	string	Numeric string with fraction
price_tax	string	Numeric string with fraction
price_total	string	Numeric string with fraction

Request body sample

{
    "type": "booking_data",
    "data": [
        {
            "company_uid": "581919935819928467",
            "booking_uid": "DR3RS5S6_airgms_GT0QUEMAKFD400FS",
            "reservation_code": "DR3RS5S6",
            "booking_status": "accepted",
            "platform_type": "airgms",
            "listing_uid": "GT0QUEMUFT28YBID_airgms_GT0QUEMAKFD400FS",
            "property_uid": "5804533058085162365",
            "guest_uid": "9WO7Y5I9C4WSCKCWG4KKWKWK0_airgms",
            "host_uid": "GT0QUEMAKFD400FS_airgms",
            "number_of_guests": 1,
            "price": {
                "currency": "USD",
                "price_base": "10.00",
                "price_extras": "0.00",
                "price_fee": "0.00",
                "price_tax": "0.00",
                "price_total": "10.00"
            },
            "local_checkin_dttm": "2021-10-10 13:00:00",
            "local_checkout_dttm": "2021-10-11 11:00:00",
            "created_dttm": "2021-10-06 20:14:10",
            "updated_dttm": "2021-10-06 20:14:15"
        }
    ]
}

Calendar data change

(Available upon request) This webhook is sent when calendar data for a date (or dates) are changed. For this webhook data objects will be in the following format:

Key	Type	Description
company_uid	string	UID of company
listing_uid	string	UID of listing
property_uid	string	UID of property
date	string	Calendar date in Y-m-d format
rate_id	string	Platform rate ID ('0' for the platforms which do not support rates and also for rate agnostic calendar data (e. g. listing availability))
currency	string	Currency code (3 symbols)
price	string	Numeric string with fraction
base_price	string	This field is reserved for future usage
is_available	int	Is listing available (1) or not (0)
min_stay	int	Minimum nights value
base_min_stay	int	This field is reserved for future usage

Request body sample

{
    "type": "calendar_data",
    "data": [
        {
            "company_uid": "581919935819928467",
            "listing_uid": "51477991_airbnb_411957375",
            "date": "2021-10-11",
            "rate_id": "0",
            "currency": "USD",
            "is_available": 1,
            "price": "100.00",
            "base_price": "100.00",
            "min_stay": 2,
            "base_min_stay": 2
        }
    ]
}

Guest details change

This webhook is sent when the guest details of one of the future bookings are changed. For this webhook data objects will be in the following format:

Key	Type	Description
company_uid	string	UID of company
guest_uid	string	UID of guest
platform_type	string	One of available platform types (see the corresponding filters section)
name	string	Guest full name
email	string[]	Array of guest emails
phone_number	string[]	Array of phone numbers

Request body sample

{
    "type": "guest_data",
    "data": [
        {
            "company_uid": "581919935819928467",
            "guest_uid": "EOJTEMLW5IOS4GWWWOGOCOS88_airgms",
            "platform_type": "airgms",
            "name": "Pavel",
            "email": [
                "pavel@example.com"
            ],
            "phone_number": [
                "+79123456789"
            ]
        }
    ]
}

Properties change

This webhook is sent when user's properties list has changed: either a property has been deleted, or a property has been merged into another property, or a new property has been created. For this webhook data objects will be in the following format:

Key	Type	Description
company_uid	string	UID of company
operation	string	create or delete
property_uid	string	UID of removed\created property

Request body sample

{
    "type": "properties_data",
    "data": [
        {
            "company_uid": "4674080625695383552",
            "operation": "create",
            "property_uid": "6848864665656201326"
        }
    ]
}

Property calendar control change

This webhook is sent when user changes which pricing management app controls property calendar. Even if control is not allowed, we save received calendar data to be applied if user re-enables the app. For this webhook data objects will be in following format:

Key	Type	Description
company_uid	string	UID of company
property_uid	string	UID of property
calendar_control_allowed	bool	Is app controls property calendar

Request body sample

{
    "type": "property_calendar_control_changed",
    "data": [
        {
            "company_uid": "4674080625695383552",
            "property_uid": "6848864665656201326",
            "calendar_control_allowed": false
        }
    ]
}

Connection revoked

This webhook is sent when user revokes access to app. For this webhook data objects will be in following format:

Key	Type	Description
company_uid	string	UID of company

Request body sample

{
    "type": "connection_revoked",
    "data": [
        {
            "company_uid": "4674080625695383552"
        }
    ]
}

Property changed

This webhook is sent when user's property has changed: either changed, or deleted, or a property has been merged into another property, or a new property has been created. For this webhook data object will be in the following format:

Key	Type	Description
company_uid	string	UID of company
Property fields as in v1/get-property

Request body sample

{
    "type": "property_changed",
    "data": {
        "company_uid": "4674080625695383552",
        "property_uid": "qc11106314",
        "name": "Superior Single Room with Sea View",
        "address": "402 W Georgia St, Vancouver, V6B 5A2",
        "checkin_time": "15",
        "checkout_time": "12",
        "beds": 1,
        "bedrooms": 0,
        "bathrooms": 0,
        "is_active": 1,
        "comment": null,
        "clean_hr": 1.5,
        "clean_tm": null,
        "clean_beds_k": 0,
        "clean_beds_q": 1,
        "clean_beds_d": 0,
        "clean_beds_s": 0,
        "clean_specials": null,
        "is_inbox_enabled": 1,
        "are_auto_reviews_enabled": 1,
        "ical_token": null,
        "location": {
          "country_code": "ca",
          "postal_code": "V6B 5A2",
          "lat": 49.279616,
          "lng": -123.1122527,
          "street": "402 W Georgia St",
          "city": "Vancouver"
        },
        "selected_insurance_settings": {
          "future_reservation_coverage": "newReservationsOnly",
          "content_and_dwelling_amount": 25000,
          "bodily_insurance_amount": 500000,
          "channel_coverage": [
            "airgms"
          ],
          "include_screening_information": true,
          "insurance_company_name": "CompanyName",
          "is_insurance_coverage_active": true
        },
        "listings": [
            "660689604_booking_6606896",
            "GHA78D5I705LYHGA_airgms_4OXKYWD7RB8KSK8GK8K4SS8K0"
        ],
        "door_access_code": null,
        "calendar_control_allowed": false,
        "currency": "CAD"
    }
}