How To: Set up Events & Actions

Events & Actions is a PubNub service that extends the PubNub platform with powerful real-time integration and event routing features. It gives you a scalable, no-code solution to perform event routing features related to your users’ behaviours and store or process these Events in a myriad of ways.

At PubNub, Events are small pieces of information generated by PubNub based on a custom explicit and implicit usage detected by the PubNub platform. The best way to think about an Event is “Stuff happens, and PubNub generates an Event based on the stuff happening.”

Event listeners allow you to filter the stream of events and collect those selected events into a queue so they can be processed with one or more actions. There are three filter options that PubNub provides: No Filter, a Basic Filter with limited customization provided by PubNub, and Advanced JSON Path filtering for more advanced filtering techniques.

Instead of handling an event using an event handler, an action is a function that PubNub will perform for each Event that matches the filter applied to the Event Listener. You can choose from a growing catalog of Actions which include:

• Make a Webhook call (i.e. call your server for each filtered event)

• Save to SQS (i.e. save each Event to Amazon’s SQS queuing service)

• Send to Kinesis (i.e. Send to Amazon’s Event Ingestion Service)

• Send to S3 (i.e. store the data in an Amazon S3 bucket)

To differentiate PubNub Functions and Events & Actions to enable real-time data processing: PubNub Functions are code snippets that run in response to an event, allowing developers to create custom logic for real-time data processing before or after an Event is published. On the other hand, PubNub Events & Actions provides an easy and scalable way to filter and process events in real-time while delivering seamless no-code integration with 3rd party services. Find out more about when you should choose PubNub Functions or Events & Actions.

Before you configure Events and Actions, here are some pre-requisites that should be set up before continuing:

1. PubNub Account: To use Events and Actions, you must have a PubNub account. If you don't have one, you can sign up for a free account on the PubNub web page.

2. API Keys: Once you've created a PubNub account, you must generate API keys to connect to the PubNub network and use its services. After creating an application and keyset, you can find your API keys in the PubNub Admin Dashboard under the "Keys" section. If they want to use Advanced JSON Path Filters and the meta Condition, users need to enable the Objects feature.

3. Basic understanding of PubNub fundamentals: You should understand how PubNub works and how to use its core features, such as publishing and subscribing to data streams. If you're new to PubNub, you can check out an interactive tour of PubNub features and the PubNub documentation for more information.

4. WebHook or another third-party service: Depending on the action you want to take in response to an event, you may need to set up a WebHook or integrate with a third-party service. Ensure you have the credentials and documentation for any third-party services you plan to use.

As said above, Event listeners wait for a specific set of conditions to occur to trigger some pre-defined action. Three filters can be applied on top of an event: No filter, which allows the Event Listener to trigger all events; a Basic Filter or an Advanced JSON path filter. Using a filter will allow you to define further the event you are trying to listen to. For example, using a Basic Filter, you can configure the event instance to only listen to a specific Channel or Sender ID. Advanced JSON path filters take this a step further and allow you to customize the filter more precisely than what PubNub has pre-defined in the Basic Filters. Learn more about Advanced JSON path filtering.

Create an Event in the PubNub portal by following the steps below:

1. Login to the Admin Portal.

2. Click the Events & Actions tab on the left-hand side of the portal.

3. Follow the popup dialog and select one of your applications

4. Follow the popup dialog and choose a keyset

5. Click the “ + Event Listener” button 

6. Customize the event name by clicking the pencil icon beside “Event listener 1”

7. Select which type of event listener you want to enable: Messages, Users, or Channels.

8. The filter type is optional but allows you to filter the event listener. 

9. Click the down arrow beside “Event Listener Type” to choose whether to use basic or advanced JSON path filtering. For this example, we'll use Basic Filters.

10. Select the attribute you want to filter on. For this demo, choose "channel" from the dropdown to filter on a specific channel.

11. Select the condition you want to filter on if you want the channel ID to be an exact match or the Channel ID just to contain the value. For this demo, select “contains” from the drop-down.

12. In the "Value" field, enter the value you want to filter on. For example, if you're going to filter on a channel named "Demo-Channel," enter "Demo-Channel" in the "Value" field.

13. Click “Save Changes”; now PubNub will listen for that specific event or condition.

After following the steps, the Event on the PubNub portal should look like the following:

Your new Event is set up to filter for events that meet your specified criteria. Any events that match your selected filters will be collected and queued for processing. By filtering out irrelevant events, you can reduce the load on your systems and respond to only events relevant to your use case.

An action is a function that PubNub will perform for each event that matches the event filters you have specified. You can choose from a growing catalog of PubNub Actions, including making a WebHook call, saving to Amazon's SQS queuing service, storing in an Amazon S3 bucket, or sending to Amazon Kinesis.

Actions can be created and configured through the PubNub Admin Dashboard and associated with one or more Event Listeners. When an event matches the filters specified in an Event Listener, the associated Action(s) will be triggered.

Follow the following steps to create an action and link to an event using the PubNub portal:

1. Login to the Admin Portal.

2. Click on the Events & Actions tab on the left-hand side of the portal.

3. Select one of the Events under Event Listeners that has been configured.

4. Scroll down and select the “+ Create Action” button. Multiple actions can be configured per event.

1. For the purpose of this how-to, go to https://webhook.site/ to get a webhook URL

2. Under “Your unique URL,” copy the URL provided

3. Back on the PubNub website, select “WebHook” and enter the copied URL.

4. You can add additional header properties, such as authentication keys, under “Additional Headers.”

5. Pair your action with the previously created event listener without leaving the Actions view. To do this, click the “+ EVENT LISTENER” button.

6. Select choose an existing event listener and select the listener that was created above.

7. Save your newly created action by clicking the save button.

8. Open the PubNub Debug console, a troubleshooting tool that allows you to test your PubNub connectivity and app integration. Add your publish and subscribe keys from your keyset. Add the UUID “admin-user” and the channel “Demo-Channel”.

9. Send a message payload from Device 1, with the following JSON format in the Message section:

After you publish a message with the format specified above, you should receive a response that looks like the following:

When you set up a Webhook with Events and Actions on PubNub, the result is that the webhook endpoint you specified will be called every time an event matching your specified filters is received on your PubNub channel. The data sent to the Webhook endpoint will be the event payload, including event details, message details, and additional metadata associated with the Event.

For Amazon SQS, you must configure an SQS queuing service and Identity Access and Management (IAM) role on the Amazon portal; for more details, check out our docs. Note that when setting up the IAM role, set the PubNub AWS account number (535363102202) as the Account ID. Using the PubNub portal, the following steps will help you connect your Amazon SQS service to PubNub.

1. Select Amazon SQS.

2. Paste both Amazon URL (queue) and ARN (role) values under the Queue URL and Role ARN fields.

3. Optionally, enable the SQS Retry option and set the expected number of action retry attempts (Number of Retries) and the time between them (Retry Interval (in seconds)).

4. Pair your action with the previously created event listener without leaving the Actions view. To do this, click the “+ EVENT LISTENER” button and select Choose an existing event listener.

5. Save your newly created action by clicking the SAVE CHANGES button.

When you set up an SQS integration with Events and Actions on PubNub, the result is that your PubNub events will be saved to an Amazon SQS (Simple Queue Service) queue. When an event is published to your PubNub channel and matches the filter criteria specified in the Event Listener, the Action will save the event data to the specified SQS queue. This allows you to efficiently process and analyze your real-time data using various Amazon services, including Lambda, Kinesis, and S3.

For Amazon Kinesis, you will have to configure an Amazon Kinesis service and IAM role, as mentioned above. Using the PubNub portal, the following steps will help you connect your Amazon Kinesis service to PubNub. Follow the steps below, as well as refer to our documentation.

1. Select Amazon Kinesis.

2. Paste both Amazon ARN values (for data stream and role) under the Data Stream ARN and Role ARN fields.

3. Optionally, enable the Kinesis Retry option and set the expected number of action retry attempts (Number of Retries) and the time between them (Retry Interval (in seconds)).

4. Pair your action with the previously created event listener without leaving the Actions view. To do this, click the “+ EVENT LISTENER” button and select Choose an existing event listener.

5. Save your newly created action by clicking the SAVE CHANGES button.

Now PubNub Events will be sent to your AWS Kinesis configuration when it matches its filter criteria. This allows you to efficiently process and analyze your real-time data using various AWS services, including Lambda, S3, and Elasticsearch.

For the S3 action, you must first configure AWS to have an S3 bucket and an IAM role.  The steps below will help you get started, but please refer to our documentation for complete instructions.

1. Select Amazon S3

2. Paste the Bucket Name and ARN (role) values under the appropriate fields.

3. Choose the region of your target bucket from the drop-down list

4. Optionally, enable Batching and set the count of items to be batched and the period of time at which batching is to occur.

5. Pair your action with the previously created event listener without leaving the Actions view.  To do this, click the “+ EVENT LISTENER” button and select “Choose an existing event listener”

6. Save your newly created action by clicking the SAVE CHANGES button.

Now, PubNub events will be sent to your S3 bucket when they match the defined filter criteria defined in the event listener.

You have learned to use Events & Actions with PubNub, listening for specific events and firing off many actions based on event data. With this powerful tool, you can carefully manage events in your ecosystem and easily integrate with various third-party services in response to user interactions. For more information on Events & Actions, check the resource links below.

• Events & Actions Documentation

• Events & Actions or PubNub Functions: Picking the right tool

• Events & Actions: How to Filter Messages Using JSONPath

• Amazon’s SQS queuing service (SQS)

• Amazon’s Event Ingestion Service (Kinesis)

Feel free to reach out to the Developer Relations Team at devrel@pubnub.com for any questions or concerns.