Events & Actions

Events & Actions (E&A) allows you to manage all the events in your application's ecosystem and send real-time data to third-party systems for storage, analytics, or machine learning/artificial intelligence without having to write code.

How it works

Events are small pieces of information generated by PubNub based on your explicit and implicit usage. They're generated during the app's lifecycle, for example, when it connects, disconnects, or makes API calls, like publishing a message or subscribing to a channel. You can react to these events with a listener and their associated actions.

ScenarioPubNub eventDescription
Device publishes a message via an API callPubNub generates a Message Publish eventThe Publish API call made by a customer’s device triggers PubNub to fire a Message Publish event. This is an explicit event.
User’s phone loses Internet connectionPubNub generates a User Disconnect eventEven though the user’s device doesn’t make an API call to PubNub, we detect that the connection is gone. This is an implicit event.

Once you've configured a listener (1) to activate upon a particular event, you can define several actions (2) that you want to occur, such as sending the data by a webhook or a queue. You can also define actions independently of creating a listener and associate them with listeners any time later.

Events & Actions is accessible via the Admin Portal.

Events & Actions UI overview

Availability

Events & Actions is available to PubNub customers on Free, Starter, and Pro plans in three tiers.

FreeIntroPro
Price for Free, Starter & Pro Plan CustomersFreeMonthly subscription feeMonthly subscription fee
Number of Events1M5MCustom
Actions per Listener13Custom
Action Types per ListenerWebhookWebhook
Amazon SQS
Amazon Kinesis
Webhook
Amazon SQS
Amazon Kinesis
RetryNoYesYes

Event listeners

Event listeners wait for different PubNub events to occur, and when they do, the listener is activated. In the Events & Actions sense, an event may happen when, for example:

  • A message is published to a specific channel.
  • A user with a particular Sender ID publishes a message.
  • The message metadata matches a pattern you define.

Each event listener may have several actions associated with it. When an event happens, say a client with the User ID of thomas_anderson publishes a message, PubNub triggers all actions associated with a particular event listener.

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

A listener with no associated actions will still activate upon a particular event, but no action will take place.

Actions per listener

The number of actions a single event listener may trigger depends on your Events & Actions tier.

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. As such, it's the first one exposed to Events & Actions. By allowing you to filter messages, you can slice your data in new ways to gain insights into your users and how they use your application.

Internal publishes

Events & Actions doesn't process the prefix/suffix-based internal publishes (such as Presence publishes to -pnpres channels).

Filters

Filters allow you to specify the event conditions that trigger the actions. You can choose one of the following options to handle your messages:

Regardless of the filter type (apart from No filter), you can identify which message part should be parsed when deciding whether to trigger a listener. Advanced JSON path allows for the highest flexibility as it can look into different data points in the event payload.

No filter

Selecting No filter doesn't filter messages and triggers actions for all messages sent through the keyset.

Basic filters

Use Basic Filters to specify the Filters, Condition, and Value parameters.

Filters
NameDescription
ChannelTrigger an action after a message is published on a specific channel.
Sender IDTrigger an action after a message is published by a specific sender.
Condition
NameDescription
Exact MatchTrigger an action only if there is an exact match.
ContainsTrigger an action if the specified value is found within the filtered content.
Value

This field requires your specific string value input.

Advanced JSON path

You can search for specific information contained in your message payload using a JSON inspection language called JSONPath. All events generated by PubNub follow a schema that's used to write JSON path expressions.

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: $.message[?(@.text contains "Wake up, Neo...")]. This searches for any message text that includes the phrase Wake up, Neo....

Let's inspect the following examples:

Match onJSON path
Channel name with RegEx$.[?(@.channel =~ /.*my_channel.*/i)]
Fields in message payload$.[?(@.message['some_property'] == 'some_value')]
Fields in message metadata$.[?(@.meta.sensor in ['warn', 'alert'])]
Combination of fields$.[?(@.channel =~ /.*some_suffix/i && @.meta.sensor_reading > 25 && @.message.status != 'error')]

Refer to the JSONPath Online Evaluator to debug your JSONPath expressions.

Event JSON schema
Message Publish

{
meta: <json>, # metadata param
message: <json>, # payload contents
channel: <string>, # channel
uuid: <string> # aka user id / sender id
}

Actions

Actions are configurable ways to send data when an event listener is activated. The current Events & Actions implementation allows you to configure a webhook to an external service or use Amazon SQS or Kinesis services.

Actions per listener

The number of actions a single event listener may trigger depends on your Events & Actions tier.

Action feedback

Every action type supports the action feedback feature which:

  • Informs you about the number of successful and failed actions in the current month.
  • Allows you to debug actions by providing error details for each failure.

Action feedback

Clicking any of the columns opens a console view of the last ten errors, where you can download an error log for the previous three days. An error means the action didn't succeed even after retrying. It typically contains such information:

  • Number of attempts
  • Timetoken of the message that triggered the action
  • Subscribe key
  • Action instance ID (a pairing between an event and an action)

Webhooks

Webhooks allow Events & Actions 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. The Webhook action supports up to four request retries with a configurable retry interval.

Webhook retries

Webhook retries aren't available for Events & Actions Free tier customers.

Amazon SQS

Events & Actions supports sending data to Amazon SQS, a message queuing service that handles medium to large datasets. The Amazon SQS action supports up to four request retries with a configurable retry interval. If the request is retried, additional metadata is added to the event payload.

AWS configuration

To use Events & Actions with SQS, you must first configure the communication between PubNub and AWS.

Amazon Kinesis

Events & Actions supports sending data to Amazon Kinesis, a data streaming service that handles large to extra-large data sets. The Amazon Kinesis action supports up to four request retries with a configurable retry interval. If the request is retried, additional metadata is added to the event payload.

AWS configuration

To use Events & Actions with Kinesis, you must first configure the communication between PubNub and AWS.

Events & Actions vs. Functions

PubNub supports two distinct approaches to event-driven processing.

  • If you're looking for a low-code solution to send real-time data moving through PubNub to a third-party system for additional processing, use Events & Actions.

  • If you're looking to change messages on the fly before publishing them, implement any custom business logic (like aggregating data), or like to write code, use Functions.

Configure Events & Actions

Events & Actions is simple to configure and set up using the Admin Portal UI. This feature comes out of the box with a robust webhook retry for paid customers and custom headers for authentication and validation.

For further information on creating and configuring your events & actions, refer to Configure Events & Actions.

Last updated on