API setup

This section covers the essential steps for successfully integrating with our APIs. Whether you want to receive push events via Webhooks or pull data from our endpoints, we've got you covered.

• Push API: Ideal for TAAP and White Label Travel Platform partners, push events deliver real-time updates directly to your system. Learn how to set up subscriptions, manage authentication, and handle retries.
• Pull API: Designed for White Label Travel Platform partners, this allows you to request data when you need it. We'll walk you through setting up token-based authentication for secure access.

Follow the guidance below to ensure a smooth integration and secure data transmission.

Push-based delivery

This might be relevant to you if you're a TAAP or a White Label Travel Platform partner interested in Itineraries data. Push events are delivered via Webhook and will be sent as an HTTP POST message to a URL you provide.

To start receiving events, you'll need to subscribe to an event type and authenticate Expedia as the sender.

Subscriptions and events

Our Subscriptions API allows you to create and manage the events you'd like to receive through our push-based delivery service. You can currently create and manage subscriptions for Itineraries update events, and we'll be adding more as they become available.

You'll need an API client ID and secret, which your commercial contact can provide.

Accessing the Subscriptions API

You'll include an access token that's specific to your business in all of your API requests. Request this token using your API credentials via the HTTP Basic Authentication mechanism.

1. Add an Authorization header with a Base64-encoded string of your API client ID and secret to the token endpoint https://analytics.ean.com/*/v1/oauth/token. Replace the * in the URL with either template or taap, depending on your partnership.
2. The token endpoint will return an access token that you'll use for subsequent API requests. For more details, refer to the Subscriptions API details.
3. Include the access token value in future API endpoint requests.

Initial authorization header example

Authorization: Basic base64.b64encode({client-id}:{client-secret})

Token request example

securitySchemes:
  oauth:
    type: oauth2
    flows:
      clientCredentials:
        tokenUrl: https://analytics.ean.com/taap/v1/oauth/token

Authenticated authorization header example

Authorization: Bearer {access-token}

Managing your subscriptions

After you've authenticated with the Subscription API, you can manage your subscriptions, including making a list of your existing subscriptions, creating new ones, and deleting ones that no longer apply.

Creating subscriptions

When creating a subscription you will need to specify:

• The endpoint URL where you want to receive events.
• The event type you want to subscribe to, including the indicator of your partnership: taap.itinerary.change or template.itinerary.change.

Note: Although you can create multiple subscriptions, duplicate subscriptions will result in duplicate event deliveries. To avoid this, list your existing subscriptions before creating new ones.

When a subscription is created, you'll receive a unique secret key to validate the HMAC (hash-based message authentication code) included with event deliveries.

To list or delete subscriptions, use the HTTP GET /subscriptions or HTTP DELETE /subscriptions/{subscription_id} endpoints, respectively. You must use a valid token.

For additional details, refer to the Subscriptions API details.

Authenticating Expedia as the sender

We'll send push events to the endpoint you provide, with each event including a hash-based message authentication code (HMAC) signature in the authorization header. You should validate this signature to ensure secure and trusted data transmission using the shared secret we'll provide when you create a subscription.

Authorization header example

"authorization": "MAC ts='1731524372777',nonce='f88e57ed-aaf5-4edd-8e58-9105817fb4cb',bodyhash='8YLHy71r5dx3PQjdcOkRuVYXaakjhbJSROEnlreQEIA=',mac='bDxvx41INtDxtkbZwTmAMADZGiFl6/xyXC1lE5ixPuY='"

Validate the HMAC signature by adding the following logic to your endpoint that receives push events. This will ensure that the events you receive are from Expedia and have not been tampered with during transmission.

Note: This example shows how to implement this validation logic in Java. You can adapt the logic to your preferred programming language, but the core steps will remain the same.

Step 1: Parse the authorization header

Extract the necessary information from the authorization header by parsing the string into its base components.

Code example

/**
 * Parse the signature string into components
 * @param signature The signature string in format "MAC ts='...', nonce='...', bodyhash='...', mac='...'"
 * @return Map of signature components
 */
private Map<String, String> parseSignature(String signature) {
    // Pattern for key='value' or key="value"
    Pattern pattern = Pattern.compile("([a-zA-Z]+)=['\"]([^'\"]*)['\"]");
    Matcher matcher = pattern.matcher(signature);

    Map<String, String> components = new HashMap<>();
    while (matcher.find()) {
        components.put(matcher.group(1), matcher.group(2));
    }
    return components;
}

Step 2: Validate the required components

Check that the required components ts (timestamp), nonce, bodyhash, and mac are present and correctly formatted.

Code example

private Boolean validateSignatureComponents(Map<String, String> components) {
    if (components.isEmpty()) {
        return false;
    }

    return components.containsKey("ts") &&
            components.containsKey("nonce") &&
            components.containsKey("bodyhash") &&
            components.containsKey("mac");
}

Step 3: Generate and validate the body hash

Generate the body hash using HMAC SHA-256 and the sharedSecretKey and confirm that it matches the hash of the request body to ensure data integrity.

Code example

/**
 * Compute body hash (HMAC-SHA256 of the request body)
 * @param body The raw request body
 * @return Base64 encoded body hash
 */
private String computeBodyHash(String body) {
    try {
        Mac mac = Mac.getInstance(HMAC_SHA256);
        SecretKeySpec secretKeySpec = new SecretKeySpec(
                sharedSecretKey.getBytes(StandardCharsets.UTF_8),
                HMAC_SHA256);
        mac.init(secretKeySpec);
        byte[] hmacBytes = mac.doFinal(body.getBytes(StandardCharsets.UTF_8));
        return bytesToBase64(hmacBytes);
    } catch (Exception e) {
        throw new RuntimeException("Failed to compute body hash", e);
    }
}

private Boolean validateBodyHash(String requestBody, String bodyHashFromHeader) {
    String computedBodyHash = computeBodyHash(requestBody != null ? requestBody : "");
    return computedBodyHash.equals(components.get('bodyhash'));
}

Step 4: Generate and validate the HMAC signature

Generate the HMAC signature including the timestamp, nonce, HTTP method, request path, host domain, port, and generated body hash, and validate it against the received value in the header to ensure authenticity.

Code example

/**
 * Generate HMAC signature using the provided components
 * @param components Parsed signature components
 * @param computedBodyHash Computed body hash
 * @param method HTTP method (e.g., "POST", "GET")
 * @param path Request path (e.g., "/api/webhooks/events")
 * @param host Host name (e.g., "api.example.com")
 * @param port Port number
 * @return Base64 encoded HMAC signature
 */
private String generateHmacSignature(Map<String, String> components, String computedBodyHash,
                                     String method, String path, String host, int port) {
    try {
        // Normalize port (use 443 for standard HTTPS ports)
        String portString = (port == 80 || port == 443) ? DEFAULT_PORT : String.valueOf(port);

        // Build signature string with newline-delimited components
        String signatureString = String.format("%s\n%s\n%s\n%s\n%s\n%s\n%s\n",
                components.get("ts"),
                components.get("nonce"),
                method.toUpperCase(),
                path,
                host,
                portString,
                computedBodyHash);

        return calculateHMAC(signatureString);
    } catch (Exception e) {
        throw new RuntimeException("Failed to generate HMAC signature", e);
    }
}

/**
 * Calculate HMAC-SHA256
 * @param data Data to hash
 * @return Base64 encoded HMAC
 */
private String calculateHMAC(String data) {
    try {
        Mac mac = Mac.getInstance(HMAC_SHA256);
        SecretKeySpec secretKeySpec = new SecretKeySpec(
                sharedSecretKey.getBytes(StandardCharsets.UTF_8),
                HMAC_SHA256);
        mac.init(secretKeySpec);
        byte[] hmacBytes = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
        return bytesToBase64(hmacBytes);
    } catch (Exception e) {
        throw new RuntimeException("Failed to calculate HMAC", e);
    }
}

private Boolean validateHmacSignature(Map<String, String> components, String computedBodyHash,
                                      String method, String path, String host, int port) {
    String generatedHmacSignature = generateHmacSignature(components, computedBodyHash, method, path, host, port);
    return generatedHmacSignature.equals(components.get("mac"));
}

Retrying event failures

If an event fails, the system will retry using an exponential backoff pattern over 7 days: first at 5 minutes, then 60 minutes, and every 12 hours thereafter. We'll retry any failure because of:

• A non-200 HTTP status code
• A timeout
• An exception from your endpoint

Subscriptions API details

For additional details on the Subscriptions API, download the OpenAPI specification.

Pull-based delivery

If you have a White Label Travel Platform site, you can implement pull-based delivery for Itineraries and Loyalty Earn data, depending on the APIs you're using.

To get access to the Loyalty Earn and Itineraries endpoints, you'll need an API client ID and secret, which you can get from your commercial contact. You'll include an access token that's specific to your business in all of your API requests. Request this token using your API credentials via the HTTP Basic Authentication mechanism.

1. Add an Authorization header with a Base64-encoded string of your API client ID and secret to the token endpoint https://analytics.ean.com/template/v1/oauth/token.
2. The token endpoint will return an access token that you'll use for subsequent API requests. For more details, refer to the OpenAPI specification.
3. Include the access token value in future API endpoint requests.

Initial authorization header example

Authorization: Basic base64.b64encode({client-id}:{client-secret})

Token request example

securitySchemes:
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://analytics.ean.com/template/v1/oauth/token

Authenticated authorization header example

Authorization: Bearer {token}

Once you've received your token, you can start making requests against any of the Loyalty Earn or Itineraries endpoints.

When requesting the service, you'll need to specify your API version. Use the servers.url value found at the top of our downloadable OpenAPI spec files. It will always correspond with the version number for the API service you're testing.

The URL should follow this structure:

https://analytics.ean.com/[product]/[API version]/[path]

You can switch between endpoints by replacing the path, but be sure to keep the protocol, domain designation, product, and API version number as laid out in the OpenAPI spec.

Endpoint examples

https://analytics.ean.com/template/v1/loyalty/earn/last_update
https://analytics.ean.com/template/v1/itineraries

To explore the data scope and the API configurations, see the schemas for API delivery:
Itineraries API delivery
Loyalty Earn API delivery