> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/docs/developers/webhooks.md).

# Webhooks

Receive events instead of polling — and the two delivery rules that surprise people.

Flow Retail can call your system when something happens — an order is settled, a product changes, stock moves. You register an endpoint against an action, and Flow Retail `POST`s a JSON payload to it.

## What a payload contains

A webhook payload is a set of **references**, not a copy of the entity. You get the action and the identifiers involved; you call the API to fetch the detail.

```json
{
  "action": "ORDER_SETTLED",
  "tenant": { "Id": 7, "Uid": "7" },
  "store": { "Id": 1, "Uid": "70" },
  "order": { "Id": 7123, "Uid": "700" },
  "tenantUser": { "Id": 7, "Uid": "9" },
  "jobId": 12345,
  "attempt": 1
}
```

Two details that break integrations if missed:

* **The nested reference keys are `Id` and `Uid`, capitalised.** The envelope keys around them (`action`, `tenant`, `order`, `jobId`, `attempt`) are lowerCamelCase. Reading `payload.order.uid` returns nothing — it is `payload.order.Uid`.
* **There is no timestamp field.** Payloads carry no `occurredAt` or equivalent. If you need event time, record your own receipt time.

Which reference fields appear depends on the action — see [Available actions](#available-actions). Absent references are omitted, with one exception: `tenantUser` is always present and is `null` when no user caused the event, such as a scheduled job. Treat every field except `action`, `jobId` and `attempt` as optional.

`jobId` and `attempt` are added by Flow Retail as the job is dispatched. **Deduplicate on `jobId`** — retries of the same event reuse it, and `attempt` increments from 1.

## Does a payload tell you what changed?

**No.** A payload never carries the new state, the old state, or which fields changed. It tells you *which* entity to look at; you fetch it to see what it is now.

`ORDER_STATE_CHANGE` is the one most often misread. Its payload is exactly the example above with the action swapped — no `orderState`. To learn that an order was cancelled, fetch it:

```http
GET /tenants/{tenantUid}/stores/{storeUid}/orders/{orderUid}
```

and read `orderState`: <kbd>OPEN</kbd>, <kbd>PARKED</kbd>, <kbd>CONFIRMED</kbd>, <kbd>CANCELED</kbd> or <kbd>COMPLETE</kbd>. Note the spelling — `CANCELED`, one L.

Always act on the state you fetch, not the one you expect. The order may have moved on since the event was queued, and parking an order that is already fully paid leaves it <kbd>COMPLETE</kbd>, not <kbd>PARKED</kbd>.

Two actions carry a value as well as references:

| Action                          | Extra field       | Contains                                                                                                               |
| ------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ORDER_LINE_RESERVATION_CHANGE` | `reservationType` | The line's new reservation: `NONE`, `WAREHOUSE`, `PURCHASEORDER`, `REQUEST_PURCHASEORDER` or `PURCHASEORDER_CONFIRMED` |
| `TILL_OPEN`, `TILL_CLOSED`      | `date`            | The day of the event, as `YYYY-MM-DD`                                                                                  |

## When `ORDER_STATE_CHANGE` fires

It does **not** fire on every state change. It fires when:

* An order is opened, parked or confirmed through the order status endpoint — including orders left open for more than 24 hours, which Flow Retail parks automatically.
* An order is cancelled — by a user, through the API, or because a coupled inter-store purchase was called off.

It fires only if the state actually changes. Parking an order that is already parked sends nothing.

It does **not** fire when:

| The order…                                      | Becomes             | Listen for instead                            |
| ----------------------------------------------- | ------------------- | --------------------------------------------- |
| Is fully paid                                   | <kbd>COMPLETE</kbd> | `ORDER_SETTLED`                               |
| Is created                                      | <kbd>OPEN</kbd>     | Nothing — there is no create event for orders |
| Is a parked order whose valid-until date passes | <kbd>CANCELED</kbd> | Nothing — see below                           |

A parked order that expires is cancelled with no webhook. Expiry follows the order's valid-until date, which defaults from the tenant setting **Default Parked Order Lifespan (days)**. If you track parked orders, re-fetch them periodically to catch expiry.

***

## Delivery, retries and timeouts

Two of these rules are the opposite of what most APIs do. Both silently lose events if you assume otherwise.

### A timeout is treated as success

If your endpoint does not respond within **10 seconds**, Flow Retail records the delivery as successful, logs the timeout, and **drops the event**. It is not retried.

Acknowledge immediately and process asynchronously. Return `200` or `202` as soon as you have the payload safely on your own queue — never do the work inside the request.

The same applies to a connection that *times out* rather than being refused. If your host accepts the connection and then stalls, that is treated as a timeout and the event is dropped. A connection that is actively **refused** is a transport error and *is* retried. A server that is down and refusing keeps its events; a server that is hanging loses them.

### `429` is retried; other `4xx` codes are not

| Your response                  | Retried?                         |
| ------------------------------ | -------------------------------- |
| `2xx`                          | No — success                     |
| `3xx`, `4xx` other than `429`  | No — event permanently discarded |
| `429 Too Many Requests`        | **Yes**                          |
| `5xx`                          | Yes                              |
| Connection refused or reset    | Yes                              |
| Connection or response timeout | No — counted as success          |

If you are overloaded, return `429`. Returning a different `4xx` for a problem you want redelivered is the most common way integrations lose events.

### Retry schedule

Retries run up to **30 times**, with this backoff:

| Retry    | Wait before it |
| -------- | -------------- |
| 1        | 1 minute       |
| 2        | 2 minutes      |
| 3        | 5 minutes      |
| 4        | 10 minutes     |
| 5        | 20 minutes     |
| 6        | 30 minutes     |
| 7        | 45 minutes     |
| 8        | 60 minutes     |
| 9        | 90 minutes     |
| 10 to 30 | 120 minutes    |

A webhook that fails every time is retried for just under two days — about 46 hours across all 30 attempts — before it is given up on.

## Securing your endpoint

Flow Retail does **not** sign webhook payloads. There is no HMAC header and no signature to verify.

Instead, you secure the endpoint with a credential that you choose when you register the webhook's HTTP transport:

| `securityType` | What Flow Retail sends                                              |
| -------------- | ------------------------------------------------------------------- |
| `NONE`         | No credential                                                       |
| `BASIC_AUTH`   | `Authorization: Basic …` from the `username` and `password` you set |
| `BEARER_TOKEN` | `Authorization: Bearer …` from the `token` you set                  |

You can also attach custom headers to the transport.

Use `BEARER_TOKEN` or `BASIC_AUTH`, and reject any request to your webhook endpoint that does not carry the credential you configured. Because there is no signature, that credential is the only thing distinguishing a real delivery from anyone else who has guessed your URL — treat it as a secret and rotate it like one.

## Available actions

There are 18 actions that fire. Every payload also carries `tenant`, `tenantUser`, `jobId` and `attempt`.

| Action                          | Fires when                                                              | References in the payload                                    |
| ------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ |
| `PRODUCT_CREATE`                | A product is created                                                    | `product`                                                    |
| `PRODUCT_UPDATE`                | A product is updated                                                    | `product`                                                    |
| `PRODUCT_MEDIA_CHANGE`          | Product media is created, updated or deleted                            | `product`, `productMedia`                                    |
| `CUSTOMER_CREATE`               | A customer is created                                                   | `customer`                                                   |
| `CUSTOMER_UPDATE`               | A customer is updated                                                   | `customer`                                                   |
| `ORDER_SETTLED`                 | An order is fully paid                                                  | `store`, `order`                                             |
| `ORDER_STATE_CHANGE`            | An order is opened, parked, confirmed or cancelled — see above          | `store`, `order`                                             |
| `ORDER_DELIVERED`               | Every line on an order is delivered                                     | `store`, `order`                                             |
| `ORDER_LINE_DELIVERED`          | A single order line is delivered                                        | `store`, `order`, `orderDelivery`, `orderProductLine`        |
| `ORDER_LINE_RESERVATION_CHANGE` | An order line's reservation changes                                     | `store`, `order`, `orderProductLine`, plus `reservationType` |
| `ORDER_RECEIPT_SETTLED`         | A receipt is settled                                                    | `store`, `order`, and usually `orderReceipt`                 |
| `ORDER_HANDLING_STATE_CHANGED`  | Handling moves to `NOT_STARTED`, `IN_PROGRESS`, `ON_HOLD` or `COMPLETE` | `store`, `order`, `orderHandling`                            |
| `PRICE_CREATE`                  | A price is created                                                      | `pricelist`, `price`                                         |
| `PRICE_UPDATE`                  | A price is updated                                                      | `pricelist`, `price`                                         |
| `STOCK_CHANGE`                  | Stock changes for a warehouse and product                               | `store`, `warehouse`, `product`                              |
| `PURCHASE_RECEIVED`             | A purchase order is fully received                                      | `store`, `purchaseOrder`                                     |
| `TILL_OPEN`                     | A till is opened                                                        | `store`, `till`, `cashReport`, plus `date`                   |
| `TILL_CLOSED`                   | A till is counted and closed                                            | `store`, `till`, `cashReport`, plus `date`                   |

`ORDER_HANDLING_STATE_CHANGED` names the handling, not its new state — fetch the handling to read it.

{% hint style="warning" %}

#### Deletes send nothing

The API accepts `PRODUCT_DELETE`, `CUSTOMER_DELETE` and `PRICE_DELETE` when you register a webhook, but Flow Retail never sends them. To detect deletions, reconcile periodically: list the entities and remove the ones that are gone.
{% endhint %}

## Example payloads

### PRODUCT\_UPDATE

```json
{
  "action": "PRODUCT_UPDATE",
  "tenant": { "Id": 7, "Uid": "7" },
  "product": { "Id": 123, "Uid": "PRD-123" },
  "tenantUser": { "Id": 7, "Uid": "9" },
  "jobId": 12346,
  "attempt": 1
}
```

Fetch the product itself from the product endpoints using `product.Uid`.

### STOCK\_CHANGE

```json
{
  "action": "STOCK_CHANGE",
  "tenant": { "Id": 7, "Uid": "7" },
  "store": { "Id": 1, "Uid": "70" },
  "warehouse": { "Id": 12, "Uid": "WH-01" },
  "product": { "Id": 123, "Uid": "PRD-123" },
  "tenantUser": { "Id": 7, "Uid": "9" },
  "jobId": 12347,
  "attempt": 1
}
```

The payload tells you *that* stock changed, not the new level. Read the current figure from the stock endpoints.

## Building a reliable receiver

1. **Verify the credential** you configured on the transport, and reject anything without it.
2. **Persist the payload and return `200` immediately.** You have 10 seconds, and a timeout is not retried.
3. **Deduplicate on `jobId`** before processing.
4. **Fetch the detail from the API** using the `Uid` values — the payload never says what changed.
5. **Return `429` when overloaded** — it is the only `4xx` that gets redelivered.
6. **Expect new fields over time.** Parse only what you use and ignore the rest.

Stuck on a delivery? Send us the `jobId` and [we will trace it](https://docs.flowretail.com/docs/developers/errors-and-troubleshooting.md).

*Last updated 24.09.2026*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flowretail.com/docs/developers/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
