Overview & Setup

When building on top of Rye’s APIs, you might want your backend to execute actions in response to Rye’s system state updating. For instance, you might want to send an email to a customer when their order is shipped by the merchant.

While you could implement this functionality by polling Rye’s APIs, this approach is inefficient and increases system load. To support event-driven architectures, Rye provides webhook functionality. Webhooks allow you to receive real-time updates when events occur in Rye’s system—such as when an order is placed, or a product’s price changes.

Wherever possible, we recommend using webhooks to receive updates from Rye’s system, rather than polling Rye’s APIs.

​

Use cases

Common use cases for webhooks include the following, but there are many other valuable use cases:

• Maintaining a local copy of Rye’s product data for search and display
• Sending order updates to customers via email or SMS
• Triggering internal alerts when orders fail to process

​

Getting started with webhooks

In order to receive webhooks from Rye, you need to tell us where you would like to receive them. The following instructions

That’s it! On every order update, a webhook will be fired at your designated endpoint.

​

Webhook payload

Rye webhooks follow a consistent structure.

interface BaseWebhook {
  /** Unique ID for this webhook. */
  id: string;
  /**
   * ID of the originating request that triggered this webhook.
   *
   * Webhooks with a common `requestId` are related to each other.
   */
  requestId: string;
  /** This is your developer ID; it will match the value of the `Rye-Verification` header. */
  developerId: string;
  /** Indicates what type of event this is. */
  type: string;
  /** This contains the actual webhook payload. The shape of this field depends on `type`. */
  data: object;
  /** Creation time of the event, as an ISO datetime.*/
  createdAt: string;
}

A comprehensive directory of webhook types can be found here.

​

Webhook verification (recommended)

For added security, Rye includes a signature header on each webhook request sent to your endpoint. This header can be used to verify the authenticity of the request. Note that depending on your webserver configuration, the header key may come through as lowercase.

​

Headers

The headers Rye sends alongside each webhook payload are described in the following table.

​

Verifying the signature

The Rye-Hmac-Signature-V1 header will contain an HMAC signature of the request body. The signature is generated using the SHA-256 algorithm using your account’s unique HMAC secret key. The cipher’s digest is then base64-encoded. In psuedocode, this looks like the following:

cipher = new_hmac(algorithm: "sha256", secret: "<<your hmac secret>>")
signature = base64encode(cipher.hash_data(request.body))

Your HMAC secret key can be found in the Rye Console on the Account page, within the Webhooks section.

​

Sample code

Here are example code snippets which show how to verify the signature of a Rye webhook using some common tech stacks:

const crypto = require('crypto');

// Your HMAC secret key
const SECRET_KEY = process.env.RYE_HMAC_SECRET_KEY;

// Inside your POST handler
app.post('/', (req, res) => {
  // Create a SHA-256 HMAC with the shared secret key
  const hmac = crypto.createHmac('sha256', SECRET_KEY);

  // Update the HMAC with the request body
  // req.body represents the POST body as a string, assuming that it hasn't been parsed to JSON
  hmac.update(req.body);

  // Compare the base64 HMAC digest against the signature passed in the header
  if (hmac.digest('base64') !== req.headers['rye-hmac-signature-v1']) {
    // The request is not authentic
    return res.status(401).send('Unauthorized');
  }
});

​

Caveats

• Rye does not currently attempt to resend webhooks that fail to deliver. Please ensure webhooks always succeed on the first try.
• Webhook delivery attempts time out after 10 seconds. If your endpoint does not successfully receive the event within that timeframe, it can cause you to miss events.
• Webhook ordering is not guaranteed. While Rye will attempt to deliver webhooks in the order they were generated, this is not always possible due to network conditions. Your system should account for this and be able to handle out-of-order events; e.g. receiving a “product updated” event before the corresponding “product created” event. The createdAt timestamp on each webhook can be used to order events on your end if necessary.