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

# Webhook event catalog

> Every event accepted by an OmniCommerce developer webhook subscription.

`POST /api/v1/webhooks` accepts the 17 event keys on this page. Event names are
stable subscription identifiers; marketplace-specific topic names never appear
in the `events` array.

## Product and catalog

| Event                       | Emitted when                                                 |
| --------------------------- | ------------------------------------------------------------ |
| `product.created`           | A product is created through a product or developer workflow |
| `product.updated`           | Persisted public product data changes                        |
| `product.deleted`           | A product is deleted through the product API                 |
| `product.price.changed`     | Price, sale price, currency, or cost-price inputs change     |
| `product.inventory.changed` | The product's catalog inventory quantity changes             |

A single product mutation can emit `product.updated` and a more specific price
or inventory event. Each delivery has its own `eventId`; consume every event
type you subscribe to and deduplicate each one independently.

See [Product webhooks](/webhooks/products) for payload fields and examples.

## Orders

| Event                  | Emitted when                                                    |
| ---------------------- | --------------------------------------------------------------- |
| `order.created`        | A committed order aggregate is first created                    |
| `order.updated`        | Public non-status order data, totals, or line aggregate changes |
| `order.status.changed` | The provider-neutral order status changes                       |
| `order.deleted`        | A stored order is explicitly deleted or legally purged          |

Order events use the versioned `2026-08-01` provider-neutral contract. See
[Order webhooks](/webhooks/orders).

## Returns

| Event                   | Emitted when                                                      |
| ----------------------- | ----------------------------------------------------------------- |
| `return.created`        | A normalized return and its current SKU-level lines first commit  |
| `return.updated`        | Amounts, identifiers, or lines change without a status transition |
| `return.status.changed` | The provider-neutral return status changes                        |

Return events use the versioned `2026-08-29` PII-free contract. See
[Return webhooks](/webhooks/returns).

## Settlements

| Event                       | Emitted when                                                                 |
| --------------------------- | ---------------------------------------------------------------------------- |
| `settlement.created`        | The first order-and-currency finance aggregate is committed                  |
| `settlement.updated`        | Amounts, fees, references, evidence counts, or reconciliation results change |
| `settlement.status.changed` | The normalized aggregate settlement status changes                           |

Settlement events are independent of order lifecycle events because marketplace
finance commonly arrives later and can be adjusted. See
[Settlement webhooks](/webhooks/settlements).

## Looks

| Event          | Emitted when                |
| -------------- | --------------------------- |
| `look.created` | A shoppable look is created |
| `look.deleted` | A shoppable look is deleted |

There is no `look.updated` subscription event today. See
[Look webhooks](/webhooks/looks).

## Test deliveries

The Webhooks settings page can send `webhook.test` to one subscription. It uses
the same signature headers, but it is not a subscription event and is rejected
if included in `POST /api/v1/webhooks`.

```json theme={null}
{
  "eventId": "delivery-test-id",
  "eventType": "webhook.test",
  "organizationId": "org_123",
  "productId": null,
  "sku": null,
  "changedFields": [],
  "occurredAt": "2026-08-29T05:00:00.000Z",
  "data": {
    "test": true,
    "message": "Webhook endpoint test from OmniCommerce."
  }
}
```

## Not yet subscribable

These resource families are planned but are not accepted subscription keys and
are not emitted as developer webhooks today:

| Resource family                        | Current status                          |
| -------------------------------------- | --------------------------------------- |
| Payout batches and cash reconciliation | Planned webhook contract                |
| Fulfillment packages                   | Planned as a separate resource contract |
| Marketplace listing errors             | AOP-only event; not a developer webhook |

Do not subscribe to guessed keys such as `payout.created` or
`fulfillment.updated`.
OmniCommerce returns `400` for any event outside the catalog.