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

1

Navigate to account settings

Head on over to the Rye Console.

2

Set up an endpoint

Enter the endpoint you would like to have webhooks sent to. Your endpoint must be accessible over the public Internet (no localhost), and be set up to receive HTTP POST requests.

3

Verify functionality

Follow our webhook testing guide to verify that you can successfully receive webhooks.

4

Implement signature verification

Each webhook is sent with a cryptographic signature that guarantees it came from Rye’s systems. Verifying this signature is important for security.

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.

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.

A note about CORS

Depending on how you have set up your backend, you may need to add these Rye headers to a CORS allowlist before they can be received.

HeaderDescription
Rye-Hmac-Signature-V1This is a cryptographic signature that verifies the authenticity of the webhook. More detailed information on how to validate this header is in the next section.
Rye-VerificationThis is the ID of your developer account. It can be found in the Rye Console under “JWT Authentication”, advertised as your issuer ID. This header can be useful in situations where you have multiple Rye developer accounts, all sending webhooks to the same endpoint.

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:

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.