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.
There are a set of measures that you can take to ensure that your subscriptions are secure and identifiable.
The first thing is to whitelist the apaleo outbound IP addresses as shown below to make your life easier.
18.104.22.168 22.214.171.124 126.96.36.199
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.
Your subscription should only be configured for the topics and properties that you require. Getting irrelevant events for topics 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.
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
With your new token, your URL would look like the following:
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.