Better Data

Integrations

Webhooks

Edit this page

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)

1import { createWebhookHandler } from '@commercegateway/commerce-gateway/webhooks';
2 
3const handler = createWebhookHandler({
4  secret: process.env.WEBHOOK_SECRET,
5  onInventoryChange: async ({ productId, available }) => {
6    "cmt">// Update your cache or notify active sessions
7  },
8  onOrderComplete: async ({ sessionId, orderId }) => {
9    "cmt">// Finalize the conversational session
10  }
11});
12 
13"cmt">// Use with a Hono or Express server
14app.post('/api/webhooks', async (c) => {
15  return await handler.handle(c.req);
16});

Supported Events

| Event | Platform | Description | |-------|----------|-------------| | inventory.updated | Shopify, Square | Change in stock levels. | | order.created | Shopify, Square | A new order was placed. | | product.updated | Shopify, Square | Change in price, description, or images. | | checkout.completed | Better Data Cloud | A 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.