How do they work?

Get to know how you can start using the Publish Event feature

So, you’ve heard about the Publish Event feature and you’re curious how it works.

At its core, the Publish Event feature revolves around Q-Flow Event Registry. Let’s dive in and walk through the first step: creating a Category.

Create your first 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.

To create a Category:

1. Open the Management Portal.
2. Select Categories in the left sidebar menu.
3. Press the Add Event Category button.
4. Give the Category a unique name.
5. Add a description for the Category.
6. Press the Create button.

Create the Event Type

Now that you have successfully created your first Category, let's add an Event Type to it.

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.

To create an Event Type for the newly created Category:

1. Be sure to be inside the newly created Category.
2. Press the New Event button.
3. Name the Event Type.
4. Add a brief description to the Event Type.
5. Define the schema of the Event Type or allow Qala to generate the JSON schema for you conveniently.
6. Press the Create button.

tip

Upon the creation of the Event Type we recommend:

• Naming the Event Type 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.
• To remove any ambiguity for the Event Type, you can add a brief description denoting what the Event Type is for and when the event is triggered.
• On the schema definition, you can simply copy an existing schema, ensuring it conforms to JSON schema standards or allow Qala to generate the JSON schema for you conveniently. Alternatively, you can create an event without a schema but it’s best practice to define the schema for your subscribers.

Create your first Topic

Now, let's move forward and create a Topic within your Environment:

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. Topics ensure that subscribers are only notified about events that pertain to their specific interests or functions, reducing unnecessary data processing or regulatory concerns.

To create a Topic:

1. Open the Management Portal.
2. Select Topics in the left sidebar menu.
3. Press the Add new Topic button.
4. Give the Topic a unique name.
5. Add a description to the Topic.
6. Select the applicable event types for the Topic. A drop-down list will show you the event type created within the Registry, grouped by the associated category.
7. Press the Create button.

Create your first Subscription

Create a Subscription for your newly created Topic.

A Subscription for a Topic in webhooks, is a request by a client (subscriber) to receive notifications for events related to a specific Topic. It involves registering a webhook URL to listen for and handle events filtered for that Subscription.

A Topic can have one or many Subscriptions, allowing multiple webhook URLs to listen out for specific events for the Topic.

1. Be sure to be inside the newly created Topic.
2. Press the Add Subscription button.
3. Give the Subscription a unique name.
4. Add a description for the Subscription.
5. Choose the events that the Subscription wants to subscribe to.
6. If applicable, you can choose to apply advanced filtering, aggregation and transformation to incoming events.
7. Set a webhook endpoint URL.
8. Configure the maximum retries for the webhook.
9. Press the Create button.
10. Once the Subscription has been created, you can view the Subscription Webhook Secret.

Publish an event to your Topic

In order to publish an Event to your Topic, you’ll need a Secret Key (check the Create an API Key section), along with the Environment ID.

The Environment ID can be conveniently accessed and copied to your clipboard by clicking the environment name on the top menu.

How to Copy the Environment ID:

1. Open the Management Portal.
2. Press the Environment Name on the top menu.
3. Press the copy icon adjcent the Enviornment ID.
4. The Enviornment ID will be copied to your clipboard.

warning

All requests to publish an event must have the environment ID on the x-environment-id header, and set x-auth-token header using the Create an API Key

An Event will only be published to the Topic if the type is a valid Event Type within the Event Registry. If you have an Event where it’s not defined in the Event Registry, or if the event is not associated with a Topic, you will receive a 400 bad request.

An array of events can be sent using the /v1/topics/{{topicname}}/events/publish endpoint.

required

Array of objects (Event) non-empty The Events to publish.

{

• "events": [

  • {

    • "type": "transaction.updated",
    • "id": "Example2",
    • "data": {

      • "customerId": "123456",
      • "name": "John Doe",
      • "email": "johndoe@letsQala.com",
      • "createdAt": "2024-04-30T08:45:00",
      • "address": {

        • "street": "123 Main St",
        • "city": "Los Angeles",
        • "state": "California",
        • "zipCode": "90210",
        • "country": "United States"

        }

      }

    }

  ]

}