Webhooks Overview & Setup
Webhooks allow you to receive real-time updates about changes in Rye’s data.
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:
Navigate to Account Settings
Go to the Rye Console.
Set Up an Endpoint
Enter your publicly accessible endpoint URL (must be accessible over the internet and capable of handling HTTP POST requests).
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"
}
Verify Functionality
Follow our webhook testing guide to ensure your endpoint correctly receives and processes webhooks.
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
Header | Description |
---|---|
Rye-Hmac-Signature-V1 | Cryptographic signature to verify the webhook’s authenticity. Refer to the verification section for details. |
Rye-Verification | Your 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
-
Compute HMAC:
- Use SHA-256 with your HMAC secret key to hash the request body.
- Base64-encode the resulting digest.
-
Compare Signatures:
- Match the computed signature with the
Rye-Hmac-Signature-V1
header. - Reject the request if they do not match.
- Match the computed signature with the
-
Handle Challenge:
- If the payload includes a
challenge
, respond with its value to complete verification.
- If the payload includes a
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.
Caveats
- Reliable Delivery: Rye does not retry failed webhook deliveries. Ensure your endpoint reliably handles requests on the first attempt.
- 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.
Was this page helpful?