Events

An event is something that happened in one of your connected systems. Events are the input to FlowAlert — everything starts with an event being sent to the API.

Event payload

{
  "event": "booking.created",
  "title": "New Booking — John Smith",
  "body": "Tour: Sunset Cruise · 4 guests · 6 PM",
  "priority": "NORMAL",
  "detail": "Additional notes or HTML content here",
  "url": "https://app.example.com/bookings/BK-1234",
  "data": {
    "booking_id": "BK-1234",
    "customer_email": "john@example.com",
    "tour": "Sunset Cruise"
  }
}

Fields

Field	Type	Required	Description
`event`	string	✓	Event key — `resource.action` format, lowercase. e.g. `booking.created`. The `flowalert.` prefix is reserved.
`title`	string	✓	Short notification title (max 200 chars)
`body`	string	✓	Main notification message (max 2000 chars)
`priority`	string		`LOW`, `NORMAL`, `HIGH`, or `URGENT` (`CRITICAL` is accepted as an alias of `URGENT`). Defaults to `NORMAL`
`detail`	string		Extended content shown when the notification is opened
`data`	object		Arbitrary key-value metadata attached to the event
`url`	string		Optional link surfaced as a tappable button when the alert is opened (e.g. a deep link to the order, booking, or dashboard page). Must be a full `http(s)://` URL.
`dedupeKey`	string		If provided, duplicate events with the same key within 10 minutes are silently dropped
`requiresAck`	boolean		Override the routing rule's acknowledgement setting for this specific event

Event keys

Event keys identify the type of event. Use dot notation and keep them descriptive:

booking.created
booking.cancelled
payment.failed
payment.succeeded
order.created
order.updated
form.submitted
maintenance.urgent
lead.created

Event keys are strings you define when sending events from your code. FlowAlert does not assign or interpret them — the key you send and the key on your routing rule just need to match. The only reserved prefix is flowalert., which is used for internal system events.

💡

Event keys are used in routing rule patterns. A rule with pattern booking.* will match booking.created, booking.cancelled, and any other key starting with booking.. Use * to catch all events.

Sites — where an event came from

If an event carries a site key inside data, FlowAlert identifies which of your sites it originated from. The WordPress plugin does this automatically on every event it sends — custom API senders can adopt the same convention:

{
  "event": "order.created",
  "title": "New order #4821 · $1,240",
  "body": "2× Sourdough Special · pickup 17:30",
  "data": {
    "site": "https://acme-bakery.com",
    "site_name": "Acme Bakery"
  }
}

Key	Sent by the plugin	Description
`data.site`	Automatic — the site's `home_url()`	The site's URL. A bare hostname (`acme-bakery.com`) works too.
`data.site_name`	Automatic — the site's title	Optional human-readable name, used until you set your own label.

What FlowAlert does with it:

Auto-registration — the first event from an unknown site adds it to Dashboard → Sites. No setup, no pre-registration. A workspace holds up to 500 sites, on every plan.
Stable identity — the URL is normalized before matching: http vs https, www. vs bare, and trailing slashes all resolve to the same site, while subdirectory installs (example.com vs example.com/shop) and non-default ports count as different sites. Moving to a new domain creates a new site — archive the old one.
Tagged history — every event is linked to its site, and Dashboard → Alerts can filter by site (including events with no site).
Prefixed pushes — once a workspace has more than one site, push titles get a [Acme Bakery] prefix so a phone full of client alerts stays legible. Single-site workspaces are left exactly as they are.
Names vs. labels — a site's name auto-fills from site_name, but a label you set by hand in Dashboard → Sites is never overwritten by incoming events, and always wins in the push prefix.

💡

Routing by site. Because site lives in the payload, routing rules can match it like any other data field — a condition on data.site routes one client's alerts to the person or team that owns that client. See Routing rules.

Site resolution never blocks delivery. If a URL can't be parsed or the workspace is at its site cap, the alert still routes and delivers — it just isn't tagged with a site.

Priority levels

Priority	Use case
`LOW`	Informational, no urgency
`NORMAL`	Standard operational alert
`HIGH`	Needs attention soon
`URGENT` (alias: `CRITICAL`)	Immediate action required. Senders may also use `CRITICAL` — it is accepted and stored as `URGENT`, so both vocabularies land on the same top tier

Event history

All events are stored and visible in Dashboard → Alerts. You can inspect the full payload, see which notifications were triggered, and check delivery status.

Quickstart Routing Rules