Webhooks

Webhooks allow your app to receive real-time notifications when events occur in a Qumra store.

Registering Webhooks

Define your webhook subscriptions in the qumra.app.json manifest file. Each subscription specifies the topics to listen for and the URI that will handle the incoming requests.

qumra.app.json

{
  "webhooks": {
    "api_version": "2025-07-01",
    "subscriptions": [
      {
        "topics": ["product.created", "product.updated"],
        "uri": "/webhooks/products"
      },
      {
        "topics": ["inventory.created", "inventory.updated"],
        "uri": "/webhooks/inventory"
      }
    ]
  }
}

Handling Webhooks

Create a route file with an action export to handle incoming webhook requests. The authenticate.admin method automatically verifies the webhook signature and parses the payload.

app/routes/webhooks.products.tsx

import { authenticate } from "~/qumra.server";

export async function action({ request }: { request: Request }) {
  const { payload, topic, storeId, admin } =
    await authenticate.admin(request);

  switch (topic) {
    case "product.created":
      console.log("New product created:", payload);
      break;
    case "product.updated":
      console.log("Product updated:", payload);
      break;
  }

  return Response.json({ success: true });
}

Available Webhook Topics

Topic	Description
product.created	Fired when a new product is created
product.updated	Fired when an existing product is updated
product.deleted	Fired when a product is deleted
product.viewed	Fired when a product is viewed
product_review.created	Fired when a new product review is created
product_review.updated	Fired when a product review is updated
product_review.deleted	Fired when a product review is deleted
inventory.created	Fired when a new inventory record is created
inventory.updated	Fired when an inventory record is updated

warning

Always respond quickly. Return a 200 status within a few seconds. For heavy processing, queue the work and process it asynchronously.

tip

The SDK automatically verifies the HMAC signature of incoming webhooks via authenticate.admin(request). See the Security page for HMAC details.