When integrating with Rye’s APIs, you might need your backend to perform actions in response to changes in Rye’s system. For example, sending an email to a customer when their order is shipped. While polling Rye’s APIs is possible, it’s inefficient and increases system load. To support event-driven architectures, Rye provides webhook functionality. Webhooks enable you to receive real-time updates when specific events occur in Rye’s system, such as order placements or product 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:
  • Data Synchronization: Maintain a local copy of Rye’s product data for search and display.
  • Customer Notifications: Send order updates to customers via email or SMS.
  • Internal Alerts: Trigger alerts when orders fail to process.

​
Getting Started with Webhooks

To receive webhooks from Rye, follow these steps:
1

Navigate to Account Settings

Go to the Rye Console.
2

Set Up an Endpoint

Enter your publicly accessible endpoint URL (must be accessible over the internet and capable of handling HTTP POST requests).
3

URL Verification Handshake

After saving your endpoint, Rye will send a verification request containing a challenge parameter. Your endpoint must respond with the exact challenge value to confirm it can receive webhooks. Rye will only save the URL if the challenge is successfully verified.Verification Request Example:
{
  "id": "e56b5b2b-40d4-491f-bab2-ecb96bc911a7",
  "developerId": "mBdwaN3QWmmvZsNYuWPdLnzIbaDM",
  "createdAt": "2024-07-22T14:30:04.367Z",
  "type": "WEBHOOK_URL_VERIFICATION",
  "data": {
    "challenge": "8eaacf92948128c760d0a25af59231693b2f930fcf8bad61d780fa2796d923bec5bc64e6da55f17196b10a10850f0fa2"
  }
}
Verification Response Example:
{
  "challenge": "8eaacf92948128c760d0a25af59231693b2f930fcf8bad61d780fa2796d923bec5bc64e6da55f17196b10a10850f0fa2"
}
4

Verify Functionality

Follow our webhook testing guide to ensure your endpoint correctly receives and processes webhooks.
5

Implement Signature Verification

Each webhook includes a cryptographic signature to verify its authenticity. Verifying this signature is essential for security.
Once set up, your endpoint will receive a webhook for every relevant event, such as order updates.

​
Webhook Payload

Rye webhooks follow a consistent structure: 
interface BaseWebhook {
  /** Unique ID for this webhook */
  id: string;
  /** Originating request ID */
  requestId: string;
  /** Your developer ID; matches the `Rye-Verification` header */
  developerId: string;
  /** Event type */
  type: string;
  /** Event-specific data */
  data: object;
  /** Event creation timestamp in ISO format */
  createdAt: string;
}
For a complete list of webhook event types, visit our webhooks events page.

​
Webhook Verification

​
Security Measures

  • Signature Validation: Each webhook includes a Rye-Hmac-Signature-V1 header to verify authenticity.
  • Challenge Response: Your endpoint must respond to the initial challenge during setup.

​
Headers Overview

HeaderDescription
Rye-Hmac-Signature-V1Cryptographic signature to verify the webhook’s authenticity. Refer to the verification section for details.
Rye-VerificationYour developer account ID, useful for endpoints handling multiple Rye accounts.
CORS Configuration: Ensure your backend allows Rye’s headers by updating your CORS policy accordingly.

​
Verifying the Signature and Handling Challenges

  1. Compute HMAC:
    • Use SHA-256 with your HMAC secret key to hash the request body.
    • Base64-encode the resulting digest.
  2. Compare Signatures:
    • Match the computed signature with the Rye-Hmac-Signature-V1 header.
    • Reject the request if they do not match.
  3. Handle Challenge:
    • If the payload includes a challenge, respond with its value to complete verification.
Pseudocode Example: 
cipher = new_hmac(algorithm: "sha256", secret: "<<your hmac secret>>")
signature = base64encode(cipher.hash_data(request.body))
Your HMAC secret key is available in the Rye Console on the Account page under the Webhooks section.

​
Testing Webhooks Locally

To test webhooks locally, you can use ngrok to expose your local server to the internet. For example, run the following command to create a public URL that forwards to your local webhook endpoint: 
ngrok http 3000
Ensure the RYE_HMAC_SECRET_KEY environment variable is set in your application. 
// npm install express body-parser crypto
const crypto = require('crypto');
const express = require('express');
const bodyParser = require('body-parser');

const app = express();
const SECRET_KEY = process.env.RYE_HMAC_SECRET_KEY;

// Parse raw body for signature verification
app.use(bodyParser.raw({ type: '*/*' }));

app.post('/webhook', (req, res) => {
  const receivedSignature = req.headers['rye-hmac-signature-v1'];
  const hmac = crypto.createHmac('sha256', SECRET_KEY);
  hmac.update(req.body);
  const expectedSignature = hmac.digest('base64');

  if (expectedSignature !== receivedSignature) {
    return res.status(401).send('Unauthorized');
  }

  const data = JSON.parse(req.body);

  if (data.data?.challenge) {
    return res.json({ challenge: data.data.challenge });
  }

  // Process the webhook event
  res.status(200).send('Event received');
});

// Start the server
app.listen(3000, () => {
  console.log('Server listening on port 3000');
});

​
Caveats

  • Reliable Delivery: Rye will attempt to deliver each webhook twice. Ensure your endpoint reliably handles requests without errors.
  • Timeouts: Webhook requests must respond within 10 seconds. Longer processing may result in missed events.
  • Event Ordering: Webhooks may arrive out of order. Use the createdAt timestamp to sequence events appropriately in your system.