Events & Actions
Free preview
This feature is available as a free preview until August 31, 2022. Starting September 1, 2022, active listeners will be billed at the same rate as the MAU edge transaction rate.
When client applications make API calls like publishing a message or subscribing to a channel, it generates events that other clients can listen for and handle.
Events and Actions (E&A) provides a way for you to centrally manage all the events that are happening in your application's ecosystem and to optionally trigger additional business logic using a listener.
Once a listener is triggered, you can define a number of actions that you want to occur, such as sending the data by a webhook or a queue.
Event listeners
Event listeners wait for different PubNub events to occur, and when they do, the listener is activated. In the E&A sense, an event may happen when, for example:
- A message is published to a specific channel.
- A user with a specific UUID publishes a message.
- Message's metadata matches a pattern you define.
Each event listener may have a number of actions associated with it. When an event happens, say a message is sent by a client with the UUID of thomas_anderson, all actions associated with a particular event listener are triggered. A single event listener may trigger up to 3 actions.
Free preview limitations
For our limited free preview, you may only define 1 action per event listener, but after your first billing cycle, you will have access to 3.
Message publish event
Messages are the cornerstone of PubNub as they contain information critical to running your application. Message Publish is the most utilized event in our system and, as such, it's the first one exposed to E&A. By allowing you to filter messages, you can slice your data in new ways to gain insights into your users and how they're using your application.
Filters
Filters allow you to specify the type of events that you want to trigger actions for. You can define your own custom payload and identify which information in a message you want to react to. You can choose either Basic Filters or Advanced JSONPath to filter your messages.
Basic Filters
Use Basic Filters to specify the Filters, Condition, and Value parameters.
Filter
| Name | Description |
|---|---|
| Channel | Trigger an action after a message is published on a specific channel. |
| Sender ID | Trigger an action after a message is published by a specific sender. |
Condition
| Name | Description |
|---|---|
| Exact Match | Trigger an action only if there is an exact match. |
| Contains | Trigger an action if the specified value is found. |
Value
Requires your own specific string value input.
Advanced JSONPath
By utilizing a JSON inspection language called JSONPath, we're able to search for specific information contained in your message payload.
For example, let's say you want to filter a specific message containing the text: "Wake up, Neo...". For this purpose, you can use a JSONPath expression like: $.message[?(@.text contains "Wake up, Neo...")]. This searches for any message text that contains the phrase Wake up, Neo....
Actions
Actions are configurable ways to transmit data when an event listener is activated. The current E&A implementation allows you to configure a webhook to an external service that forwards the message data for further analysis. You can associate 3 actions per event listener.
Free preview limitations
During the free preview, you can only have 1 action per event listener.
Webhooks
Webhooks allow E&A to integrate with other third-party servers in a fully event-driven manner that's useful in data collection and analysis. For a webhook to be functional, you must configure an endpoint to receive the event payload. Optionally, you can add custom headers. For an example of a webhook payload, refer to Configure E&A.
Feature availability
The current implementation of E&A allows you to use a webhook only for an external service that forwards the message data for further analysis.
Configure events and actions
E&A is simple to configure and set up using the Admin Portal UI. This feature comes out of the box with a robust webhook retry and custom headers for authentication and validation.
For further information on creating and configuring your own events and actions, refer to Configure E&A.