Understanding Rally Hooks

This document provides a high-level overview. For a more comprehensive understanding, please consult our API Reference for Rally Hooks and WebHooks.

Rally Hooks Defined

Rally Hooks offer an efficient method for our APIs to solicit information from an external system. They direct our APIs to the precise location to request the needed data, be it the required endpoint for product information, taxes, or discounts.

Contrary to WebHooks that operate as a one-directional optimistic mechanism, Rally Hooks incorporate a two-way interaction. They compel a response from the connector, resulting in bidirectional communication.

This might appear similar to a standard API request-response cycle, but it operates on a different principle. The API, in the role of the publisher, requests data from a URL it subscribes to, referred to as the subscriber.

Hooks flow

The central link in this setup is between our publisher and the subscriber. The subscriber indicates to the publisher which URL to ping and the format of the data the publisher sends. In turn, the subscriber responds with a prearranged structure (as outlined in these API docs/per hook), containing the requested/expected data.

The Nature of Rally Webhooks

WebHooks can present significant load tasks. Certain scenarios like product updates or fulfillment might trigger thousands, or even tens of thousands, of WebHooks simultaneously.

Therefore, to ensure maximum scalability within the connector, we highly recommend the following:

  1. The connector should accept the incoming WebHook from the Platform, respond with a 2xx status code immediately, and initiate a pre-processing Job.
  2. Once the payload is restructured to align with Rally's data formats/expected payloads (as specified in our API docs), the connector should forward them to the appropriate URLs of Rally's APIs. These requests should be signed with a X-HMAC-SHA256 header, to confirm their authenticity.
  3. Since Rally manages all the payment processing, ensure that any refund webhooks are implemented and relayed to Rally for refund issuance.

Basic Security Measures

Each incoming request to your Rally Hook URL is consistently signed with an HMAC and dispatched as a header of topic X-HMAC-SHA256. This allows you to verify and validate the authenticity of incoming requests. The process of decoding and calculating HMACs is explained in a separate section below.

HMAC Fundamentals for Rally Hooks and WebHooks

Our API anticipates the response and payload to be encoded and signed with an identical HMAC header X-HMAC-SHA256, accompanied by the newly computed HMAC. This security measure aids in averting potential man-in-the-middle attacks.

HMAC Calculation

We employ a simple HMAC implementation.
Copy
Copied
base64_encode(hash_hmac('sha256', string $data, string $secret, true));

Key Generation

To generate the signature, we need an Api-Secret to sign a payload (request/response). We use a random 40 character secret from the App → OAuth Client. The id of the OAuth client also serves as the Api-Key. Each new App automatically creates an OAuth client.

Key Transmission

The keys are NOT sent to a connector. Instead, the App developer should manually copy and paste them. Both the Api-Key and Api-Secret are available in the App/Extensions App area in the Partners dashboard.

Signing Requests

The HTTP client signs the request by incorporating the following HTTP headers:

Copy
Copied
X-HMAC-SHA256 : <HMAC>

Alternatively, the hash can be added to the query parameters under the hmac key. To verify the hmac present in the query parameters, you need to exclude it. The HMAC is a base64_encoded string.

Explanation of Parameters

  • external_id: This ID corresponds to the platform's resource. For instance, if the resource is a Product, this would be the Product's ID as registered in the Platform.
  • line_item.subtotal: This is the price of a line item, after deducting discounts, and excluding taxes.
  • line_item.total: The total price of the line item, after accounting for discounts and including taxes.
  • order.subtotal: This is the sum of all line items, before taxes and after discounts, excluding shipping.
  • order.total: The sum of all line items, after taxes and discounts, with shipping included.
Copyright © Rally Commerce, Inc. 2023. All right reserved.