HomeGuidesAPI Reference
Guides

Flipdish events (v3) overview

A catalog of every Flipdish Webhooks (v3) event type, what triggers it, and when to use it, with links to the full schema for each.

This page lists every event type available through Flipdish Webhooks (v3). For how to create a subscription, verify requests, and handle delivery, see Subscribe to Flipdish Events (v3). For the exact JSON payload of any event, follow the Definition link in the table.

Event catalog

Event typeCategoryFires whenStatusDefinition
menu.published.v1Menu PublishingAn org publishes a menu (new or updated), making it available to sales channels and integrations.Generally availablemenu.published.v1
menu.validation.failed.v1Menu ValidationA menu fails validation after a publish attempt.Generally availablemenu.validation.failed.v1
menu.item.snoozed.v1SnoozesA menu item (category item or option set item) is snoozed (temporarily hidden).Generally availablemenu.item.snoozed.v1
menu.item.unsnoozed.v1SnoozesA previously snoozed menu item becomes available again.Generally availablemenu.item.unsnoozed.v1
sales_channel.snoozed.v1SnoozesA sales channel is snoozed (temporarily taken offline).Generally availablesales_channel.snoozed.v1
sales_channel.unsnoozed.v1SnoozesA previously snoozed sales channel is brought back online.Generally availablesales_channel.unsnoozed.v1
sales.created.v1Sale Created (legacy)A sale is created via the Sales Management API only.⚠️ Deprecating soonsales.created.v1
sale.created.v1Sale Created (new)Any sale is ingested by Flipdish, on any channel (POS, kiosk, web, marketplace, or API). Carries the full sale payload inline.Closed betasale.created.v1
sales.cancelled.v1Sale CancelledA sale is cancelled.⚠️ Deprecating soonsales.cancelled.v1
sale.updated.v1Sale UpdatedA sale ingested by Flipdish is materially updated (items, charges, or discounts changed).Closed betasale.updated.v1
sales.pos.status.updated.v1Sale Status Updated (legacy)A sale's POS / kitchen status changes.⚠️ Deprecating soonsales.pos.status.updated.v1
sale.status.updated.v1Sale Status Updated (new)Any sale transitions to a new lifecycle status, on any channel. Unifies POS and delivery status into one event.Closed betasale.status.updated.v1
sales.delivery.status.updated.v1Sales Delivery Status UpdatedA sale's delivery status changes (e.g. dispatched, on the way, delivered).⚠️ Deprecating soonsales.delivery.status.updated.v1

When to use which event

Menu events

  • menu.published.v1 — subscribe to keep a downstream system (POS, aggregator, cache) in sync whenever a menu is published.
  • menu.validation.failed.v1 — subscribe alongside menu.published.v1 to alert on publish attempts that failed validation, instead of only detecting the absence of a publish.
  • menu.item.snoozed.v1 / menu.item.unsnoozed.v1 — use to reflect an item's temporarily-unavailable/available state in an external menu display or POS.
  • sales_channel.snoozed.v1 / sales_channel.unsnoozed.v1 — use to reflect a whole channel going offline/online (e.g. store paused on a marketplace).

Sale events

Flipdish exposes two event families for sales, which differ in channel scope and payload shape — see Sale webhook events (beta) for the full comparison:

  • sales.* (legacy) — fires only for sales created through the Sales Management API, and carries identifiers only (you must call the API to fetch line items/charges/payments).
  • sale.* (new, closed beta) — fires for sales on any channel (POS, kiosk, web, marketplace, API) and carries the full sale payload inline, so no follow-up API call is needed. Use this family if you want a simpler handler with no round-trip, or need sale.updated.v1 to track mid-lifecycle changes (there is no equivalent in the legacy family).
🚧

sales.* is being deprecated soon

The sales.* family (sales.created.v1, sales.cancelled.v1, sales.pos.status.updated.v1, sales.delivery.status.updated.v1) is slated for deprecation in the near term as sale.* matures. Do not build new integrations against sales.* — request access to the sale.* beta instead (see Sale webhook events (beta) for how to get access). Existing subscribers should plan their migration now rather than waiting for a deprecation notice.

What to use instead

Instead of (sales.*, legacy)Use (sale.*, new)
sales.created.v1sale.created.v1
sales.pos.status.updated.v1 + sales.delivery.status.updated.v1sale.status.updated.v1 (single unified status event covering both)
sales.cancelled.v1sale.status.updated.v1 with status SALE_CANCELLED — there's no separate cancelled event in the new family
(no equivalent)sale.updated.v1 — new: tracks mid-lifecycle changes to items, charges, and discounts

sale.* also drops the follow-up API call: the full sale payload is inline, and brandId is included where sales.* payloads don't carry it.

Related