Skip to main content

Push it! Webhooks in apaleo

The notification service allows you to build or set up apps which subscribe to certain events on apaleo (webhooks). When an event is triggered, we send an HTTP POST payload to the configured URL.

Webhooks can be used to send reservation confirmations or check-out emails with the invoice attached, issuing mobile keys on check-in and much more.

Configure webhooks

Webhooks can be configured per property and topic. All you need to do is subscribe to a topic on https://notifications.apaleo.com, or https://notifications.apaleo.io, if you are still in a building and testing phase.

The URL you provide in the request needs to be secure and start with https. It needs to be reachable from apaleo.com or apaleo.io. If you're not sure, check with your security or ops team, if any firewalls prevent incoming traffic on (usually) port 443, and ask to whitelist us.

To unsubscribe, delete the subscription.

Events

When subscribing, you can choose events from which topic you want to receive. A topic is grouping events of several types. The available events are:
TopicType
Reservationcreated
amended
guest-data-modified
checked-in
checked-out
canceled
set-to-no-show
Systemhealthcheck
The list of types within one topic can grow in the future, make sure your implementation is prepared for unexpected event types appearing in the payloads.

Events we send to your webhooks all have the same structure:
{     
    "topic": "Reservations",
    "type": "created",
    "id": "ec5a1fe4-331c-450a-915c-5caa231cc825",
    "accountId": "HFTF",
    "propertyId": "HFTF-AADS",
    "data": {
        "entityId": "XPGMSXGF-1"
   },
    "timestamp": 1530741026
}
Typically, you might want to use this information to query more data. For example, get the reservation entity by its ID. The 'data' element is optional and can in the future contain payloads with different schemas. For now, it's always the entityId.

Ping

After you subscribe, apaleo sends a health-check event. If that fails, the subscription will fail and return an error.
apaleo will continue pinging you every two minutes for each subscription - that way you know that everything still works, even if no new events happened. If the same URL endpoint is used for two different subscriptions, it will receive two health checks.
You can also trigger the ping yourself, using the healthcheck API. This is a great way to test if your URL can generally be reached and handle the request. The message sent by the ping is a sample reservation created event.

Guarantees and error handling

Under normal circumstances, you will receive the notification latest 60 seconds after the actual event happened in apaleo.
Events are not sent in any specific order, and it can happen that you receive, for example, a 'reservation canceled' before a 'reservation created' event. You can use the timestamp to order events.
Each event is delivered at least once. You can deduplicate them using the ID field.

The notification service expects your endpoint to respond with a 2xx success code, also for event types you are not supporting. When something goes wrong, return 4xx or 5xx error codes, just like you always do. If a delivery attempt fails, we will try resending the event every minute.
Even if one of the events is not acknowledged by you with a 2xx, apaleo continues sending the other events.


Comments

Popular posts from this blog

Getting Started with apaleo APIs

Have a look You can find all of apaleo's API on api.apaleo.io. We use Swagger to describe it, and to generate our documentation.

Sign up The first step is to sign up for an account. After you finish signup you will be able to login to our apaleo app and start configuring your properties. Also you can use the same credentials to access our API using Swagger. Get access for app We're still new and want to get in touch with you before we grant you access. Contact us at api@apaleo.com, to get your very own client credentials that lets you play with the API in our sandbox.
Use it apaleo APIs are protected using OAuth2 - the de-facto standard for API security. Here's a short guide to get you started:

Step 1: To get access to our APIs, you need to use your client id and secret to obtain an access token. Don't have one? Contact us at api@apaleo.com.

Combine your client id and secret into a string, separated by colon yourClientId:YourClientSecret and encode with Base64. This wi…

Connect your app with OAuth 2.0

What is this all about? When you connect your app to apaleo, it can read or modify data, or even trigger entire business flows of a hotel. But before gaining access to any of the resources in the REST API, it must get permission from the hotel. This guide will walk you through the authorization process (described in greater detail by the OAuth 2.0 specification). Note: apaleo's OAuth 2.0 implementation supports the standard authorization code grant type. You should implement the application flow described below to obtain an authorization code and then exchange it for a token. (The implicit grant type is not supported.) Terminology Before learning more about the details of the authorization process, make sure that you are familiar with some of the key terms that are used in this guide: Client: Any application that would like access to a hotel's data. A user (usually the hotel's owner or admin) must grant permission before the client can access any data.API: apaleo REST API. T…

Channel Integration Guide

With the channel integration you can subscribe for availability, rates and inventory (ARI), create new bookings and modify existing bookings. 
The BasicsGet your sandbox account and check out this guide to learn how you can connect to the apaleo APIs.
API Client All apaleo APIs are described as swagger documents. That lets you generate API clients directly from the swagger.json files. There is a large community, providing client generators for almost every language. For example, swagger code generator is a good project, which allows generation of API clients for Java, PHP, C#, NodeJS and more. This gets you up to speed very fast and as a bonus you can access API documentation within the auto-generated methods and models.
Sandboxapaleo.io is our – and your – playground to do first steps with the API, up to your final integration. Use it to interactively explore the API or to learn the apaleo concepts by navigating the user interface.

These are the links you need to know