Webhooks

In the dynamic world of student accommodations, staying updated is crucial. That's where webhooks come into play. Webhooks provide a powerful way to receive real-time data updates directly from the Housemates Connect API, ensuring that your platform remains synchronized with the latest changes.

Instead of continuously polling our API for changes, webhooks deliver the data straight to you. By registering a webhook endpoint in your dashboard, you can effortlessly listen to various events and updates, reducing the need for frequent API calls and optimizing your application's performance.

Benefits

By integrating our webhooks, you can cache the API results on your platform. If anything changes on our end, we'll promptly send you the data, ensuring that your cache remains fresh and your users get the most accurate information.

Registering webhooks

To register a new webhook, you need to have a URL in your app that Housemates Connect can call. You can configure a webhook from the dashboard. Pick the events you want to listen for, and add your URL.

If your Webhook endpoint is not publicly accessible, don't worry, we have got you covered. You can specify an access token. You can also register any additional headers you want to include in the request.

Now, whenever something of interest happens in Housemates' system, a webhook will be fired off by Housemates Connect. In the next section, we'll look at how to consume webhooks.

Consuming webhooks

When your app receives a webhook request from Housemates Connect, check the type attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a room, property, etc.

{
  "type":"contract.added",
  "payload":{
    "bookingPeriod":{
      "id":"01H8HCHJNNWKVH6409ATCJ3Z8R",
      "startDate":"2023-10-01",
      "endDate":"2024-05-01",
      "contract":{
        "holding_fee":10,
        "maximum_bookings":12,
        "instalments":1,
        "price_per_week":164.32
      }
    },
    "roomType":{
      "id":"01H8EBAWYJ4EB4ZQJNE4QJGP6F",
      "name":"Studio Apartment Gold"
    }
  }

In the example above, a contract was added, and the payload type has all the relevant data including the room id and name that it was added to. You can use this information to update your database or perform any other actions.

Event types

Stay ahead with real-time updates tailored for your platform's needs. Our webhooks cover a range of events, ensuring you're always in sync with the latest changes.

Booking Periods

Whenever there's an alteration to a contract, following events are triggered:

{
  "type": "contract.updated",
  "payload": {
    "id": "01H8HCHJNNWKVH6409ATCJ3Z8R",
    "startDate": "2023-10-01",
    "endDate": "2024-05-01",
    "contract": {
      "holding_fee": 10,
      "maximum_bookings": 5,
      "instalments": 1,
      "price_per_week": 164.32
    }
  },
  "roomType": {
    "id": "01H8EB8K1QT72M86690XYWHBV3",
    "name": "Studio"
  }
}

Room type

Whenever there's an alteration to a room type, following events are triggered:

{
  "type": "room.deleted",
  "payload": {
    "id": "01H9NAPYMXJ73CZRATV0XZKY2A",
    "name": "Ensuite Apartment Gold",
    "slug": "26aN5X8V",
    "property": {
      "id": "01H8CG0BPREDZ5TB5MS3V8GM9X",
      "name": "Gainsborough house",
      "slug": "gainsborough-house"
    }
  }
}

Booking

Whenever a booking is updated, following event is triggered:

{
  "type": "booking.updated",
  "payload": {
    "id": "01H9QYA9G0P3G97AX53TNAAGAY",
    "stage": "Pending Refund - Student Cancelled",
    "api_partner_id": "01H98G14YN0Q8ZFWMY719AFJ0V"
  }
}

Property

Whenever there's an alteration to a Property, following events are triggered:

{
  "type": "property.updated",
  "payload": {
    "id": "01H8CG0BWQ2RKQJGWXAKR239A0",
    "status": "published",
    "title": "Alexander Building Change",
    "location": "Manchester",
    "location_slug": "manchester",
    "address": {
      "city": "Manchester",
      "region": "",
      "country": "United Kingdom",
      "postcode": "M32 0PS",
      "firstLine": "20 Highway Road",
      "secondLine": ""
    },
    "offer_amount": 100,
    "currency": "GBP",
    "virtual_tours": [],
    "rooms": []
  }
}

Enquiry

Whenever there's an update to the status of an enquiry created via the API, the following events are triggered:

{
  "type": "enquiry.updated",
  "payload": {
    "id": "01HMDHM6RE3RMXGBDQQXVNZGCM",
    "status": "booked",
    "metadata": []
  }
}