Notifications

This page outlines the Notifications Service, which sends you alerts for booking events.

Overview

Rapid API Notifications is a solution that lets you integrate with Rapid more closely than ever. When changes occur that can impact your business, Rapid will push details of the change directly to your systems via standard POST messages. With our push notifications you can remain informed, simplify operations, and scale your business.

We currently support notifications for all booking events that occur outside of our API. So, if a call center makes a change or a hotel cancels a booking, you'll be notified immediately. This is just the beginning, more notification event types will be coming soon.

By enabling a seamless integration with your business these notifications serve to complement the following Rapid products and services.

• Rapid
• Affiliate Voyager agent booking tool
• Partner and customer support services

We now offer a Test API for all event types supported for Notifications. See full details in the next major section below. If you do not wish to set up your own requests, you can also use our new Notifications Tester tool.

Supported message types

Rapid Notifications can inform your systems with a message for the following events:

Message schema and details

All messages adhere the schema outlined below. As new message types are added for different events the schema may vary.

Each message is an HTTPS POST request with a JSON message body.

Please note: Partners need to be enabled for every event type individually to be able to receive notifications. If you would like to enable a new Notifications API event type, please reach out to Rapid support.

Example for itinerary.agent.create

{
     "event_id": "dbacce6c-afcb-4b23-ae66-48050757551c",
     "event_type": "itinerary.agent.create",
     "event_time": "2017-08-09T16:47:32.039Z",
     "itinerary_id": "8091234567890",
     "email": "customer@example.com",
     "message": "An agent created a new itinerary.",
     "affiliate_reference_id": "b086d299-2f1f-4134-a23c-f4a1c9286fac"
 }

Example for itinerary.supplier.confirm

{
    "event_id": "e02d6f41-4708-476f-915d-8a7032942e94",
    "event_type": "itinerary.supplier.confirm",
    "event_time": "2018-04-28T20:31:03.423Z",
    "itinerary_id": "8999989898988",
    "email": "alice@example.com",
    "message": "The supplier confirmed one or more rooms on this itinerary.",
    "affiliate_reference_id": "R194193582",
    "rooms": [
        {
            "confirmation_id": {
                "expedia": "926784314",
                "property": "BEF23123AA"
            }
        },
        {
            "confirmation_id": {
                "expedia": "926784315"
            }
        }
    ]
}

Example for itinerary.message.received

{
  "event_id": "1aed5641-7285-4c42-b079-f5f2f139d148",
  "event_type": "itinerary.message.received",
  "event_time": "2023-11-14T02:33:18.860105363Z",
  "itinerary_id": "9025254271673",
  "email": "john@email.com",
  "message": "We accept your request for river view room. Looking forward to your visit",
  "affiliate_reference_id": "b086d299-2f1f-4134-a23c-f4a1c9286fac"
}

Integration

Receiving a message

To start receiving notifications, you will need to stand up an endpoint that can accept a POST message that will be pushed to your endpoint. The endpoint should:

• Be publicly accessible.
• Have HTTPS and TLS 1.2 or above enabled.
• Configure a valid TLS certificate, which is trusted by most modern applications (a self-signed certificate might not be trusted).

Work with your Rapid Integration Consultant to get set up and provide them with:

• A list of event types you want to subscribe to (listed above).
• The URL for your endpoint to handle messages.

We are working to provide you with self-service tools to test your integration. Until then, your Integration Consultant can help you make test bookings to confirm that you're receiving notifications for the offline events you subscribed to.

Important configuration notes

• Rapid uses cloud-based servers - ensure your listener endpoints are configured to receive notification pushes from different potential IP addresses.
• If you wish to change your endpoint URL, you must keep the original URL live until we validate your new URL for receiving notification pushes. Contact your Rapid representative before making such changes.
• Only one URL may be used for notifications – variation on event_type or other criteria is not supported.

Handling a message

When you receive a message that a booking event has occurred, use the itinerary ID and email address from the message to retrieve the latest booking details.

Messages may arrive un-ordered. Refer to the timestamp to determine ordering and retrieve the itinerary for booking events to obtain the updated status.

After receiving the message, your integration must respond with the appropriate HTTP status code. Any message that does not receive a 200-level status code will be considered undelivered and will be queued for a retry by the notification service.

Undeliverable messages

If we are unable to successfully deliver a message to your endpoint, we will automatically retry following the schedule below:

• First retry after 5 minutes.
• Second retry after 1 hour.
• Subsequent retries every 12 hours for 7 days (14 total).

You may receive a duplicate message if we don't receive a confirmation of receipt (200 OK status code) and the message gets queued for retry. You can identify a duplicate message by locating the same event_id but a later timestamp than the original.

Undeliverable Notifications API

This request returns any undelivered notifications for your subscription and test endpoints. Messages are returned based on the API key provided. Messages are considered undeliverable and moved into storage for retrieval by this API after 7 days of active delivery attempts (see previous section).

• Undeliverable messages will be returned only once. Any messages returned by your request will be removed from the data store. Plan your response handling for this API accordingly.
• Up to 25 undelivered messages are returned with each request.
• Requests to api.ean.com will return both test and production notifications in one response. Requests to our test endpoint, test.ean.com, are not officially supported. We recommend not using the test endpoint as soon as your production endpoints are live, as doing so may return production notifications and subsequently delete them.

Message schema and details

Undeliverable messages returned by this API adhere to the same schema as production notifications, as outlined in the previous sections above.

Example - 2 undelivered messages

[
    {
        "event_id": "e02d6f41-4708-476f-915d-8a7032942e94",
        "event_type": "itinerary.agent.change",
        "event_time": "2018-04-28T20:31:03.423Z",
        "itinerary_id": "1204309424793",
        "email": "alice@example.com",
        "message": "An agent changed this itinerary.",
        "affiliate_reference_id": "R194193582"
    },
    {
        "event_id": "fe97op1b-595a-406e-8e0e-90108d5cb4a1",
        "event_type": "itinerary.agent.cancel",
        "event_time": "2018-05-24T04:08:50.839Z",
        "itinerary_id": "1204329124126",
        "email": "bob@sample.net",
        "message": "An agent canceled one or more rooms on this itinerary.",
        "affiliate_reference_id": ""
    }
]

Notifications Test API

The Rapid Notifications Test API allows you to request test notifications to be sent to your specified test endpoint to verify your integration with the Notifications Service. You can also use our Notifications Service Tester to fire test notifications directly to your endpoint without building your own requests.

Important notes

This service's request function is not present for the production Notifications API, you cannot send requests to the live endpoint to trigger or refresh production notifications. Requests are offered via this test API for testing purposes only.

Since this API is for test purposes only, its POST request trigger is only available via test.ean.com.

Message schema and supported message types

All test notifications adhere to the same schema and the same message types as a production notification, as outlined in the Notifications API documentation prior to this section.

Integration

Receiving a message

To start receiving test notifications, you will need to stand up a publicly accessible HTTPS endpoint that can accept a POST message that will be pushed to your endpoint.

Work with your Rapid Integration Consultant to get set up and provide them with:

• A list of event types you want to subscribe to for testing (listed above in the previous section).
• The URL for your test endpoint to handle test notifications.

If you fail to receive a test notification after 30 minutes of requesting, please reach out to your Rapid Integration Consultant to help you resolve your issue.

Important notes

Important notes

• In the notifications you receive, there will be no distinctions between a test notification and a production notification. We strongly recommend you to set up an endpoint specifically for test notifications to positively isolate test vs. production messages.
• When you set up different endpoints for test and production, you will only receive test notifications at your test endpoint and, likewise, you will only receive production notifications at your production endpoint.

By setting up different endpoints for test and production, you will only receive test notifications at your test endpoint and, likewise, you will only receive production notifications at your production endpoint.

Verifying notifications

In order to verify that notifications originate from Rapid we will be sending a request header to validate the event.

When Rapid sends a notification, you will be receiving an authorization header. This is the same authorization header that you send with any request to the API.

Rapid will be sending the authorization header in the format as below:

Authorization: EAN
APIKey=yourAPIKey,Signature=sha512Hash,timestamp=UNIXTimestampUsedForTheSignature

Validation

To validate the event, you will need to compare the signature SHA512 hash in the header with one that you generate using your API key, shared secret, and the timestamp in the request header.

Refer to the signature authentication reference page on how to construct the hash.

Important notes

API details

Explore the notification-related endpoint definitions on this page, then use the API Explorer or another testing software to get an understanding of how the examples and schema definitions compare to the actual output.

Additional resources

Whether you're looking to try out all the Rapid API endpoints or to download its OpenAPI specs or our Postman collection, we have you covered.