Understanding Rally HooksThis 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.
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:
- The connector should accept the incoming WebHook from the Platform, respond with a 2xx status code immediately, and initiate a pre-processing Job.
- 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-SHA256header, to confirm their authenticity.
- Since Rally manages all the payment processing, ensure that any refund webhooks are implemented and relayed to Rally for refund issuance.
Basic Security MeasuresEach 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 WebHooksOur 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 CalculationWe employ a simple HMAC implementation.
base64_encode(hash_hmac('sha256', string $data, string $secret, true));
Key GenerationTo 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 TransmissionThe keys are NOT sent to a connector. Instead, the App developer should manually copy and paste them. Both the
Api-Secret are available in the App/Extensions App area in the Partners dashboard.
The HTTP client signs the request by incorporating the following HTTP headers:
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.