Skip to main content
Webhooks allow your commerce platform (Shopify, Square, etc.) to push real-time updates to the LLM Gateway, ensuring that the AI always has the latest intelligence.

​
Why use Webhooks?

While the gateway proxies most requests live, webhooks are essential for:
  • Inventory Alerts: Proactively notifying the AI when a hot item goes out of stock.
  • Order Confirmation: Updating the sessionId when a user completes a checkout on your web storefront.
  • Catalog Refresh: Triggering a re-index of your search data when products are added or removed.

​
Configuration

If you are using the Better Data Cloud, you can configure webhooks via the dashboard. If you are self-hosting, you can use our built-in webhook handlers.

​
Setup (Self-hosted)

import { createWebhookHandler } from '@betterdata/commerce-gateway/webhooks';

const handler = createWebhookHandler({
  secret: process.env.WEBHOOK_SECRET,
  onInventoryChange: async ({ productId, available }) => {
    // Update your cache or notify active sessions
  },
  onOrderComplete: async ({ sessionId, orderId }) => {
    // Finalize the conversational session
  }
});

// Use with a Hono or Express server
app.post('/api/webhooks', async (c) => {
  return await handler.handle(c.req);
});

​
Supported Events

EventPlatformDescription
inventory.updatedShopify, SquareChange in stock levels.
order.createdShopify, SquareA new order was placed.
product.updatedShopify, SquareChange in price, description, or images.
checkout.completedBetter Data CloudA conversational checkout was successful.

​
Security

Every webhook request must be signed. The gateway automatically verifies:
  1. Signatures: HMACS from Shopify, Square, or Better Data.
  2. Timestamps: Prevents replay attacks.
  3. Payload: Ensures the data matches the expected schema.

​
Troubleshooting

  • 403 Forbidden: Your WEBHOOK_SECRET likely doesn’t match the one provided by your commerce platform.
  • Timeouts: Webhooks should return a 200 OK within 2 seconds. Move heavy processing to a background queue.