> ## Documentation Index
> Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Keep your gateway in sync with your commerce platform

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](/hosted/overview), you can configure webhooks via the dashboard. If you are self-hosting, you can use our built-in webhook handlers.

### Setup (Self-hosted)

```typescript theme={null}
import { createWebhookHandler } from '@commercegateway/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

| 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.