Skip to main content

Q-Flow Concepts

Q-Flow concepts terminology and definitions.

Organisation​

The Q-Flow Organisation represents your organisation and lets you manage licenses and billing with Q-Flow. An Organisation exists in a single region (e.g. EU, US), containing Security Principals, Users and Environments. An Organisation can have many environments.

Environment​

An environment contains topics to which events are published, and subscriptions to those topics through which events are delivered. An Environment can have one or many Topics associated to it.

An Environment serves three main purposes:

  • Configure and Manage the Event Registry
  • Configure and Manage Topics and Subscriptions
  • Logically isolate data and event processing from other Environments as Environments do not share information with each other

Topic​

A Topic is a specific subject or category of events that can be subscribed to. It groups related event types, allowing subscribers to listen for and respond to relevant events within that topic. A topic could represent a specific subject, multiple categories or be limited to specific circumstances, like an individual company/tenant.

tip

Topics ensure that Subscribers are only notified about events that pertain to their specific interests or functions, reducing unnecessary data processing or regulatory concerns.

Event​

An occurrence of potential interest to subscribers. Event(s) are published to a topic.

EventType​

An event type in webhooks specifies the kind of event that triggers the webhook. It defines the particular action or occurrence, such as "customer.created" or "order.completed," that initiates the webhook call. Naming an eventType with a noun followed by a verb clearly indicates what entity is affected and what action occurred, enhancing readability and understanding. For example, "customer.created" specifies that a customer was created.

Category​

A Category is a logical grouping that Event Types can be associated with one another. There is no rules or limitation on category groupings, but to aid subscribers, the categories should have logical grouping. For example, all events pertaining to a customer could be conveniently grouped together. Or all Transactional events can be grouped together.

API Secret Key​

An API secret key is a confidential alphanumeric string used in conjunction with an API key to authenticate and authorize requests to an application programming interface (API). It acts as a security measure to ensure that API calls are made by authorized users or applications and helps protect against unauthorized access.

Subscription​

Receives events published to a topic and delivers matching event Types to an endpoint. A Subscription will only have access to the available Event Types on the Topic. You can choose which specific Event Types to filter for on the Subscription, along with the Webhook URL. A Topic can have one or many Subscriptions, allowing multiple webhook URLs to listen out for specific events for the Topic.

tip

Subscriptions can filter for specific Event Types on a Topic, filtering for specific interests or functions, reducing data processing, data minimisation or regulatory concerns.

Publisher​

A publisher in webhooks is the entity that creates and sends event notifications. It generates events based on specific actions or changes within its system and pushes these events to registered subscribers.

Subscriber​

A subscriber in webhooks is the entity that receives event notifications from a publisher. It registers a webhook URL to listen for and handle events from the publisher, responding to relevant occurrences as they happen.

Webhooks​

Webhooks are automated messages sent from one application to another when a specific event occurs. They are real-time notifications delivered via HTTP POST requests to a predefined URL, allowing the receiving system to instantly react to the event without continuous polling.

Webhook URL​

A webhook URL is an endpoint provided by a subscriber (Subscription) where event notifications are sent by the publisher (published to a Topic). It is the address to which HTTP POST requests containing event data are delivered, enabling the subscriber (Subscription) to process and respond to these events in real-time.

Event Retries and Exponential back off​

If an error is returned by the Subscriber endpoint, Q-Flow will automatically perform the retry using the cadence described below:

Q-Flow will wait 30 seconds for a response after delivering a message. After 30 seconds, if the endpoint hasn’t responded, the message is queued for a retry. Q-Flow uses an exponential backoff retry policy for event delivery to increase successful deliveries without human intervention. You can configure the maximum retry attempts within the endpoint set-up. For example, if you configure the retry attempts to the maximum, it will attempt multiple times over a 24-hour period.

  • 10 seconds
  • 30 seconds
  • 1 minute
  • 5 minutes
  • 10 minutes
  • 30 minutes
  • 1 hour
  • 3 hours
  • 6 hours
  • Every 12 hours up to 24 hours

Webhook Signatures​

Webhooks play a crucial role in integrating Q-Flow events with external systems. To ensure secure communication, Q-Flow utilises webhook secrets and digital signatures to validate the authenticity and integrity of the incoming webhook requests.

Q-Flow Advanced Query​

Q-Flow Advanced Query empowers you to filter, aggregate, and transform your incoming events using intuitive SQL syntax. By writing concise SQL clauses, you can extract precisely the data you need, combine and summarize complex information, and reshape event payloads for downstream services.

  • Filter: Include or exclude events based on event types or specific conditions within the payload.
  • Aggregate: Summarize event data to discover trends or performance insights.
  • Transforming: Restructure event payloads for simplified consumption.