Events & Actions

Free offering

Events & Actions is now a free offering with one listener and one webhook with no retry.

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 several 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 User ID publishes a message.
  • Message's metadata matches a pattern you define.
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.

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 User ID of thomas_anderson, all actions associated with a particular event listener are triggered. A single event listener may trigger up to 3 actions.

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 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.

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.
Exact MatchTrigger an action only if there is an exact match.
ContainsTrigger an action if the specified value is found.

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 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.


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.

e&a ui overview

For further information on creating and configuring your own events and actions, refer to Configure E&A.

Last updated on