Best practices for webhooks

Webhooks provide a powerful method to track what is going on in apaleo and to take actions within your app. Review these best practices to ensure your webhooks remain secure and function seamlessly with your integration.

Secure subscription

There are a set of measures that you can take to ensure that your subscriptions are secure and identifiable.

Whitelist IP

The first thing is to whitelist the apaleo outbound IP addresses as shown below to make your life easier.

34.240.36.71
52.212.76.75
63.33.249.221

HTTPS

The webhook service will send all types of events as a POST request to the endpointUrl that you have set up for your subscription. The endpointUrl must be working via HTTPS. Your app should also ideally be hosted on a secure server.

Event types

Your subscription should only be configured for the events and properties that you require. Getting irrelevant events that you do not need, will put unnecessary strain on your server.

Handle duplicate events

Webhooks might occasionally be sent more than once. We advise you to guard against duplicate events by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not process already-logged events.

Unique token

This next one is optional, but highly recommended, appending a unique token to your URL can help you authenticate and certify that you are receiving a valid webhook notification.

For instance, let’s say that you want to receive notifications on the following endpoint

https://www.example.com

With your new token, your URL would look like the following:

https://www.example.com/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5

In the example above the URL has a JWT token attached to it for identification. This specific approach would allow you to use a single base URL and identify for which client the event is intended based on the token.

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.