API Documentation

Overview ¶

Webhooks are a system of notifications that you can receive when an event has occurred in your rentl.io account. Rather than requiring you to pull information via our API, webhooks will push information to your destination when events occur.

A Webhook is basically just a POST request that is sent to a specific URL you have specified in your account settings. Each request body is json encoded and response status < 300 is expected. More info about payload and retries can be found in separate sections.

Retries ¶

Webhook events are sent as json encoded POST request to URL you have specified in your development settings. For each sent webhook if response status code is equal or greater then 300 event will be sent again after 1 hour. Rentlio will try to resend each webhook 5 times in total. If response code is >= 300 after all 5 attempts, this event will be discarded. If number of failed attempts reaches failure limit (50 failures), webhook will be suspended and no further deliveries will be made. Suspended webhooks can only be activated by Rentlio staff member. If you encounter this scenario please contact us via support widget from web app.

Because of possible network or other failures, there can be a duplicated messages that are sent to your webhook endpoint. To process this correctly on your side each event has Id property that will be same for each webhook retry. You can use this identificator to ignore already sent messages.

Security ¶

Endpoints & Data

We decided to allow non https endpoints to be used for webhooks. Because of that, you will not be able to receive sensitive data via webhook payload. If you will need any additional data you can combine webhooks with api calls to receive all needed data.

Private token

When creating new webhook, besides url you can specify additional token field. This token field is then sent via POST request as part of payload. Value of token can be used to be sure webhook is sent by someone who knows token value, in this case Rentlio system. Tokens should be secret and you should avoid sharing it in publicly accessible areas such GitHub, client-side code, and so forth.

Request ¶

Each webhook message is sent as json with following format, where payload depends on event.type. For specific events payload please go to Events section

Request example for Reservation Created Event

Here you can find complete example of one possible webhook message. Please note that all types of messages will have same format, only payload object will change depending on event.type. You can find payloads for specific events in payloads section.

  {
    "token": "!S3cure3D",
    "event": {
      "type": "reservation-created",
      "id": "565cc7e7-3b00-4e59-b817-135bdfe78025",
      "payload": {
        "id": 145987,
        "propertiesId": 19543,
        "unitsId": 98782653,
        "arrivalDate": 1485820800,
        "departureDate": 1486166400,
        "adults": 2,
        "childrenAbove12": 0,
        "childrenUnder12": 1,
        "totalNights": 4,
        "note": "early departure",
        "guest": {
          "id": 551109,
          "name": "John Doe"
        },
        "status": 1
      }
    }
  }

Events ¶

Rentlio currently sends several events that you can differentiate using “type” property. Below you can find all webhook events.

Reservation Created

This event will be sent whenever a new reservation is created using Rentlio Web App. Type field for this event will be set to reservation-created. Payload field will hold Reservation object. Attributes for this object can be found in Payload Section under Reservations.

Reservation Updated

This event will be sent when reservation is updated using Rentlio Web App. Type field for this event will be set to reservation-updated. Payload field will hold Reservation object. Attributes for this object can be found in Payload Section under Reservations.

Reservation Canceled

This event will be sent when reservation is canceled using Rentlio Web App. Type field for this event will be set to reservation-canceled. Payload field will hold Reservation object. Attributes for this object can be found in Payload Section under Reservations.

OTA Reservation Received

This event will be sent when reservation is received from one of OTA channels like booking.com. Type field for this event will be set to ota-reservation-received. Payload field will hold Reservation object. Attributes for this object can be found in Payload Section under Reservations.

OTA Reservation Modified

This event will be sent when reservation is modified from one of OTA channels like booking.com. Type field for this event will be set to ota-reservation-modified. Payload field will hold Reservation object. Attributes for this object can be found in Payload Section under Reservations.

OTA Reservation Canceled

This event will be sent when reservation is canceled from one of OTA channels like booking.com. Type field for this event will be set to ota-reservation-canceled. Payload field will hold Reservation object. Attributes for this object can be found in Payload Section under Reservations.

Guest Checked In - On

This event will be sent when guest (reservation) is marked as checked in. Type field for this event will be set to guest-checkedIn-on. Payload field will hold Reservation object. Attributes for this object can be found in Payload Section under Reservations.

Guest Checked In - Off

This event will be sent when guest (reservation) checked in status is turned off. Type field for this event will be set to guest-checkedIn-off. Payload field will hold Reservation object. Attributes for this object can be found in Payload Section under Reservations.

Guest Checked Out - On

This event will be sent when guest (reservation) is marked as checked out. Type field for this event will be set to guest-checkedOut-on. Payload field will hold Reservation object. Attributes for this object can be found in Payload Section under Reservations.

Guest Checked Out - Off

This event will be sent when guest (reservation) checked out status is turned off. Type field for this event will be set to guest-checkedOut-off. Payload field will hold Reservation object. Attributes for this object can be found in Payload Section under Reservations.

Payloads ¶

Payload attribute of event object hold actual event data, like reservations, guests or invoices. Below

Reservation