Intro to notifications
Note: If you are interested in this feature, contact your Technical Relationship Manager before implementing it.
The notification service (also referred to as "webhooks") enables us to push real-time notifications to your service endpoint when asynchronous events occur. Notifications are not "bundled"; they are sent as they occur. HTTPS is used to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your system.
To enable notifications, you must create and configure a callback configuration and then subscribe to events types. The callback configuration and its subscriptions are collectively referred to as the "notification profile". One profile is used for all lodging partners.
If multiple GraphQL capabilities are implemented, you may want to create multiple callback configurations (one callback URL is specified per configuration) and then you can subscribe to specific event types. For example, you could create one callback configuration for property status events and one for reviews events. (The notification profile comprises all callback configurations and their subscriptions.)
Currently, the following event types are supported:
- Messaging:
MessageThreadCreated
(mandatory, partner must subscribe to this event type)MessageReceived
- Property status:
PropertyStatusMinRequirementMissing
PropertyStatusChanged
- Reviews:
GuestReviewSubmitted
ReviewsApproved
ReviewsManagementResponseApproved
ReviewsManagementResponseRejected
Overview of queries and mutations
Here is an overview of the queries and mutations available to you to implement notifications:
Mutation or query name | Description |
---|---|
createNotificationCallbackConfig mutation | Creates the callback configuration for the partner account, including the callback URL (where notification events are sent when they occur), API key, partner email address, and request timeout value. If your notification profile does not exist, this mutation will create the profile, too. |
updateNotificationCallbackConfig mutation | Updates the callback configuration, including the callback URL, API key, and request timeout value. |
refreshNotificationCallbackConfigSecret mutation | Refreshes the secret of the callback configuration. |
deleteNotificationCallbackConfig mutation | Deletes a callback configuration using the callback ID. |
sendTestNotification mutation | Sends a test notification using the specified event type and payload. The notification is sent to the configured callback URL. |
subscribeNotificationEventType mutation | Subscribes a callback configuration to notifications (by event type). |
unsubscribeNotificationEventType mutation | Unsubscribes from event types. |
updateNotificationEventTypeSubscription mutation | Updates the callback ID associated with the registered event type. |
notificationProfile query | Retrieves the partner profile. |
notificationEventTypes query | Retrieves all available event types. |
undeliveredNotifications query | Retrieves any undelivered notifications for a given event type. |
Enabling notifications
The following is an overview of the process to enable notifications. Before beginning, share your callback URLs with your TRM and wait for confirmation before completing these steps. Be sure to complete the steps for each callback configuration, if implementing more than one callback service endpoint (URL).
Generate an API key that you can use when registering your callback URL. Our team then generates a secret along with the expiration date and time of the secret. You can use the secret to validate the signature of payloads when you receive notifications from the webhooks service.
By default, the secret is valid for one year (you can determine when it will expire using the
secretExpirationDateTime
field). Note that if the secret expires, notifications fail to be sent for active subscriptions, though we attempt to retry sending them (according to the retry policy for the event type). If the secret is refreshed during these retry attempts, notifications will be sent successfully.The API key and signature are passed in the HTTP headers of the notification. The timestamp is in epoch time. The signature is a Base64 encoded HMAC-SHA256 hash created using the timestamp and notification payload as the text string and using the secret as the key. The format of the string is timestamp.payload (period is the delimiter), where payload is the full payload of the notification.
Here is an example of the headers:
“transactionId”: “11111111-1111-11ec-97a3-5d06cc689918" “api-key”: “apiKey” “x-eg-notification-timestamp”: “1674149042995" “x-eg-notification-signature”: “sha256=3VmZm10hD3/HUEStwf+BsTLP7/csgtECzIj0Ap8BYiY=”
Create a service endpoint as an HTTPS endpoint (callback URL) on your local server, and then deploy your endpoint so that it’s a publicly accessible HTTPS URL.
- The URL must be able to accept a notification payload, and it must return HTTP status code 200 after successful receipt of the notification. Downstream processing of the event must occur asynchronously. (If you subscribe to notifications before the callback URL can accept traffic, our retry logic will generate unnecessary errors in our monitoring reports. If you do not return status code 200, we continue to resend the notification to your server as per retry policy.)
- Your endpoint must use Transport Layer Security (TLS) 1.2 or 1.3, to provide over-the-wire encryption (HTTPS).
Create a callback configuration, which registers your callback URL, and subscribe to event types using these mutations:
createNotificationCallbackConfig
mutation, which creates the callback configuration, including the callback URL, API key, partner email address, and request timeout value (this also creates the notification profile if it does not exist)subscribeNotificationEventType
mutation, to subscribe to event types (you can use thenotificationEventTypes
query to retrieve the list of available event types)
Additional mutations and queries are available.
Verify the authenticity of requests (to make sure the requests are from Expedia) by
- Verifying the API key provided in the request header
- Confirming the security hash that you generate is same as what we send along with the payload
In the event that you have issues receiving a webhook notification (because of a database failure, network outage, unavailable callback URL, and so on), we attempt to resend the notification as follows (as defined by our retry policy):
- Property status: every hour for seven days
- Reviews events: every 25 seconds, up to 50 retry attempts
- Messaging events: every hour for one day
Notification payloads
This section provides format and examples of each payload type.
Messaging payloads
Format:
1{2 "event_name": "<event_name_value>",3 "creation_time": "<UTC_timestamp>", \\timestamp when the message was created (even for retries)4 "notification_id": "<notification_id>",5 "payload": {6 "property_id": "<expedia_property_id>",7 "message_thread_id": "<thread_id>", \\for message threads8 "message_id": "<message_id>", \\for messages9 "from_role": "<sender>",10 "reservation_id": "<expedia_reservation_id>", \\present if associated with message/thread11 }12}
Examples:
- MessageThreadCreated
- MessageReceived
1{2 "notification_id": "63376d68-651a-11ed-9022-0242ac120442",3 "event_name": "MessageThreadCreated",4 "creation_time": "2023-01-10T17:13:36.140Z",5 "payload": {6 "property_id": 15239779,7 "message_thread_id": "63676d68-651a-11ed-9022-0242ac120432",8 "reservation_id": "63676d68-651a-11ed-9022-0242ac120882"9 }10}
Examples:
- PropertyStatusMinRequirementMissing
- PropertyStatusChanged
1{2 "event_name": "PropertyStatusMinRequirementMissing",3 "creation_time": "2023-09-26T07:50:51.726Z",4 "notification_id": "8c7ffeec-5eb6-4cd7-8557-0f6d9290f359",5 "payload": {6 "property_id": "71888474",7 "checkpoints": [8 {9 "name": "HasImages",10 "status": "false"11 },12 {13 "name": "HasRates",14 "status": "false"15 },16 {17 "name": "HasBookingType",18 "status": "false"19 },20 {21 "name": "HasCancellationPolicy",22 "status": "false"23 },24 {25 "name": "HasHouseRules",26 "status": "false"27 },28 {29 "name": "HasCheckInCheckOut",30 "status": "false"31 },32 {33 "name": "HasPropertyDetails",34 "status": "false"35 },36 {37 "name": "HasPropertyDescription",38 "status": "false"39 },40 {41 "name": "HasBathroom",42 "status": "false"43 },44 {45 "name": "HasMaxOccupancy",46 "status": "false"47 },48 {49 "name": "HasPropertyType",50 "status": "false"51 }52 ]53 }54}
Reviews payloads
Format:
1{2 "event_name": "<event_name_value>",3 "creation_time": "<UTC_timestamp>",4 "notification_id": "<notification_id>",5 "payload": {6 "property_id": "<expedia_property_id>",7 "eg_reservation_id": "<expedia_reservation_id>", \\when a traveler submits a review8 "supplier_reservation_id": "<supplier_reservation_id", \\when a traveler submits a review9 "review_id": "<review_id>"10 }11}
Examples:
- GuestReviewSubmitted
- ReviewsApproved
- ReviewsManagementResponseApproved
- ReviewsManagementResponseRejected
1{2 "event_name": "GuestReviewSubmitted",3 "creation_time": "2023-10-04T16:02:58.978Z",4 "notification_id": "9c065ff3-7c21-4eef-be11-da11f543590c",5 "payload": {6 "eg_reservation_id": "5ee844ca-e753-491b-a391-be8598597259",7 "supplier_reservation_id": "19043678",8 "property_id": "82898394"9 }10}
Creating a callback configuration
This mutation creates the callback configuration, including the callback URL (where notification events are sent when they occur), API key, and request timeout value.
Here is an example:
- Request
- Response
1mutation {2 createNotificationCallbackConfig (3 input: {4 callbackUrl: "https://testcallbackurl.com",5 apiKey: "newapikey",6 requestTimeoutSeconds: 50,7 contactEmail: "partner@email.com"8 }9 ) {10 callbackConfig {11 id12 callbackUrl13 secretExpirationDateTime14 requestTimeoutSeconds15 contactEmail16 }17 secret18 }19}
Retrieving available event types
To determine the event types to which you can subscribe, use the notificationEventTypes
query.
Note: Not all event types are applicable to conventional lodging partners at this time. Refer to each capability's overview page for the list of event types that are available for the capability.
Here is an example:
- Request
- Response
1 query {2 notificationEventTypes {3 name4 description5 }6}
Subscribing to notifications
Use the following mutation to subscribe to an event type, to receive notifications of that type when they occur. You must subscribe one at a time.
Here is an example:
- Request
- Response
1mutation {2 subscribeNotificationEventType (3 input: {4 eventType: "GuestReviewSubmitted",5 callbackConfigId: "1969081f-8380-4dbd-9a19-c26fc1747b06"6 })7 {8 eventType9 callbackConfig {10 id11 callbackUrl12 requestTimeoutSeconds13 secretExpirationDateTime14 }15 }16}19```json20{21 "data": {22 "subscribeNotificationEventType": {23 "eventType": "GuestReviewSubmitted",24 "callbackConfig": {25 "id": "074af31e-c583-4bab-9636-aa79a76221a4",26 "callbackUrl": "https://callbackUrl.com",27 "requestTimeoutSeconds": 60,28 "secretExpirationDateTime": "2024-05-18T15:52:40"29 }30 }31 }32}
Retrieving a notification profile and its subscriptions
To review your notification profile, including the callback URL(s) and event type subscriptions, use the notificationProfile
query.
Here is an example:
- Request
- Response
1query {2 notificationProfile {3 callbackConfigs {4 id5 callbackUrl6 requestTimeoutSeconds7 secretExpirationDateTime8 contactEmail9 }10 subscriptions{11 product12 eventTypeSubscriptions {13 eventType14 callbackConfig {15 id16 }17 }18 }19 }20}
Refreshing the secret
If the API key's secret is about to expire, you can update it using this mutation.
Here is an example:
- Request
- Response
1mutation {2 refreshNotificationCallbackConfigSecret (3 input: {4 callbackConfigId: "1969081f-8380-4dbd-9a19-c26fc1747b06"5 })6 {7 callbackConfigId8 secret9 secretExpirationDateTime10 }11 }12}
Updating a callback configuration
To change an attribute of the callback configuration, such as the request timeout value, use this mutation.
Here is an example:
- Request
- Response
1mutation {2 updateNotificationCallbackConfig (3 input: {4 callbackConfigId: "1969081f-8380-4dbd-9a19-c26fc1747b06",5 requestTimeoutSeconds: 50,6 contactEmail: "partner@company.com"7 })8 {9 callbackConfig {10 id11 callbackUrl12 secretExpirationDateTime13 requestTimeoutSeconds14 contactEmail15 }16 }17}