Events API

Send an event

POST /v1/events

Authenticated with an API key (X-Api-Key header).

curl -X POST https://api.flowalert.io/v1/events \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $FLOWALERT_API_KEY" \
  -d '{
    "event": "booking.created",
    "title": "New Booking — John Smith",
    "body": "Sunset Cruise · 4 guests · 7 PM",
    "priority": "NORMAL",
    "detail": "Customer notes: wheelchair access required",
    "data": { "booking_id": "BK-5512", "tour": "Sunset Cruise" }
  }'

Field	Type	Required	Description
`event`	string	✓	Event key — a string you define, in `resource.action` format, lowercase, e.g. `booking.created`. Must match the key on your routing rule. The prefix `flowalert.` is reserved.
`title`	string	✓	Push notification title (max 200 chars)
`body`	string	✓	Notification body (max 2000 chars)
`priority`	string		`LOW` · `NORMAL` · `HIGH` · `URGENT` (`CRITICAL` accepted as an alias). Defaults to `NORMAL`
`detail`	string		Extended content shown when notification is opened (max 10,000 chars)
`data`	object		Arbitrary key-value metadata attached to the event. Two keys are conventions: `data.site` (the originating site's URL) and `data.site_name` register the event to a site for grouping, filtering and push prefixes
`url`	string		Optional URL associated with the event
`dedupeKey`	string		If set, duplicate events with the same key within 10 minutes are silently dropped
`requiresAck`	boolean		Override the routing rule's `requiresAck` setting for this specific event

Response 201:

{
  "ok": true,
  "eventId": "evt_abc123",
  "eventType": "booking.created",
  "matchedRules": 0,
  "notificationsQueued": 0
}

matchedRules and notificationsQueued are always 0 in the response — rule matching happens asynchronously in the background queue.

Deduplicated response — when dedupeKey matches an event from the last 10 minutes, no new event is created and the response carries the original event's id:

{ "ok": true, "eventId": "evt_original", "deduplicated": true }

💡

Limits: requests are rate-limited (HTTP 429 when exceeded), and each plan has a monthly event quota — over-quota sends return HTTP 403 with an explanatory message. Event keys with the reserved flowalert. prefix are rejected.

List events

GET /v1/workspaces/:workspaceId/events

Internal dashboard endpoint — see Authentication.

Query params:

Param	Default	Description
`page`	`1`	Page number
`limit`	`50`	Items per page

Response 200:

{
  "total": 142,
  "page": 1,
  "limit": 50,
  "items": [
    {
      "id": "evt_abc123",
      "eventKey": "booking.created",
      "title": "New Booking — John Smith",
      "priority": "NORMAL",
      "receivedAt": "2026-05-11T12:00:00.000Z",
      "_count": { "notifications": 3 }
    }
  ]
}

Get event

GET /v1/workspaces/:workspaceId/events/:eventId

Returns the full event with payload, notifications, and delivery status.

Authentication Routing Rules