Latest

Blog Detail Title

Short Content Here

by Author Name

Date Published

Developer

Push it! Webhooks in apaleo

Andrea Stubbe May 2, 2019

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://webhook.apaleo.com.

The URL you provide in the request needs to be secure, start with https and have a valid certificte. It also needs to be reachable from apaleo.com. 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.

Our outbound IP addresses are:

  • 34.240.36.71
  • 52.212.76.75
  • 63.33.249.221

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:

Topic Type
Reservation created
  amended
  guest-data-modified
  checked-in
  checked-out
  canceled
  set-to-no-show
  city-tax-added
  unit-assigned
  unit-unassigned
Folio balance-changed
Invoice created
  canceled
RatePlan created
  rate-changed
System healthcheck

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": "Reservation",
    "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.

Andrea Stubbe

Posted by

Andrea Stubbe
Andrea started coding as a kid, paused that for some years trying to find more interesting things, but then ended up doing that for a living. After working as a freelancer, researcher, teacher, and a normal employee in small and giant corporations, she fulfilled her childhood dream and co-founded a company a year ago. Being a fan of microservices since before she knew that term, she’s still contemplating how and if to use them in micro-sized companies.
Comments

RECENT ARTICLES

by Andrea Stubbe

06/13/2019

Digital guest journey with apaleo

apaleo is building software for hotels, and our users are people that work at hotels. To create amazing guest experiences we need you, creators of guest facing ...

by Benjamin Schmid

01/20/2019

Upsell Integration Guide

This guide explains how you can connect your upselling application, and offer extra services or room upgrades to guests. If you are new to apaleo APIs, head ...

WANT MORE AMAZING THINGS?

Subscribe to our a-list for all the fun:

  • Keep up to date with hotel trends
  • Understand what matters most to hotel clients
  • Sweet gifs and special offers

Get it in your inbox every Monday ;)

By entering your email you expressly consent to receive our newsletter every week and other material related to...