How to use the Events & Actions API

PubNub’s Events & Actions (E&A) allows you to manage all the events in your application’s ecosystem and send relevant real-time data to your own server or third-party systems for storage, processing, and more without without writing code.

Events & Actions can ingest events from many sources, apply a filter based on the data within those events, and then export that data into external systems (actions). If you would like to learn more, please see the Events & Actions product page or documentation.

This article will assume you are familiar with E&A and will focus on the Events & Actions API, which can be used to create events, actions, and their associations through a REST API.

At the time of writing, access to the E&A API is only available on request. Please use this form to request access. Full documentation will be provided after your request is approved; I have tried to make this article self-sufficient, but you might need to refer to the documentation for full context.

Terminology

As the documentation explains, the terminology used for E&A differs slightly in the API from what you might see in the portal.

Please bear in mind:

Where the API refers to a Router, this is the same as an E&A action seen in the portal.
Where the API refers to a Route Input, this is the same as an E&A event listener seen in the portal.
Where the API refers to a Route, this is the connection between an event listener and an action. In the portal, this is the equivalent of associating a listener with an action.

Support

The list of features supported by Events & Actions is continually improving, and the intention is for the E&A API to support all available events, actions, and filters. Please refer to the E&A API documentation for a definitive list, but at the time of writing, the list of supported features consists of:

Event Listeners: Messages, Users, Channels, and Mobile Push Notifications.

Actions: Webhook, SQS, Kinesis, S3, Kafka, IFTTT, AMQP

Filters: No filter, Basic filter, Advanced filter based on JSONPath

Endpoints

The E&A API exposes three primary endpoints:

Route Input: Create, Read, Update, or Delete route inputs (event listeners)
Router: Create, Read, Update, or Delete routers (actions)
Routes: Create, Read, or Delete the connection between Route Inputs and Routers. The Create API allows you to optionally create the Route Input or the Router in the same call as creating the Route. For clarity, this article will create all three components separately, but please refer to the documentation for more information on combining the calls.

Worked Example: Webhook

The following example shows how to create a Route Input to listen for messages published on channel testchannel and export those messages to the specified Webhook.

Authentication

The E&A REST API uses a session token to authenticate each call. This can be obtained from the https://admin.pubnub.com/api/me endpoint as follows:

1
2
3
4
5
6
curl --location 'https://admin.pubnub.com/api/me' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "<YOUR LOGIN>",
    "password": "<YOUR PASSWORD>"
}'

The response will look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
   "result": {
       "created": 1720528927,
       "expires": 1720562759,
       "modified": 1720533959,
	...
       "token": "REDACTED",
       "user": {
		...
       },
	...
   }
}

Take a copy of the token field which will be used in subsequent API calls. Note the created and expires fields define when you will need to authenticate with the API again. This is a UNIX timestamp, not a PubNub timetoken.

Creating the Route Input

We want to create a Route Input to listen for messages published on the channel testchannel. The call looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
curl --location 'https://admin.pubnub.com/api/ena/v2/routes/route-inputs' \
--header 'X-Session-Token: <YOUR SESSION TOKEN>' \
--header 'X-Subscribe-Key: <YOUR SUBSCRIBE KEY>' \
--header 'Content-Type: application/json' \
--data '{
 "endpoint": {
   "platformName": "PUBNUB",
   "messageTypeId": "3d2e31bb-6a4e-4211-afbd-e4134685e77f"
 },
 "name": "Created Event Listener",
 "filters": [
   {
       "field": "channel",
       "value": "testchannel",
       "type": "EXACT_MATCH"
   }
 ]
}'

The response from this API will contain the same fields as the call to GET existing Route Inputs, explained shortly.

Where did the messageTypeId come from?

Every event source has its own messages, and those messages have a specific type.

There are two ways to find out the messageTypeId for the message type you are interested in:

The easiest way is to create an event listener using the portal UI, configure the event as needed, and then use the E&A API to retrieve the event, as explained shortly.
The E&A API exposes a /v2/messages/producers/{producer-id}/messages-types API which will return the types associated with the producer you have specified. Producers are available through the /v2/messages/sources/{source-id}/producers, and the source id is returned from /v2/messages/sources.

How are filters specified?

The above example shows a basic filter that looks for an exact match of the channel name. Filters are a lot more flexible than this and more detail is given in the documentation. There are three ways to determine a filter definition:

I recommend just creating the filter using the portal UI for Events & Actions, as described for the messageTypeId, above. Use the E&A API to GET that created event, explained next, and then copy/paste the filter definition
A dedicated API is available that returns the filters available for a given messageTypeId, /v2/messages/message-types/{message-type-id}/filters.
Schemas are available for the filters in the documentation.

Retrieving existing Route Inputs

You can GET all route inputs (event listeners) using the following API call:

1
2
3
curl --location 'https://admin.pubnub.com/api/ena/v2/routes/route-inputs' \
--header 'X-Session-Token: <YOUR SESSION TOKEN>' \
--header 'X-Subscribe-Key: <YOUR SUBSCRIBE KEY>'

The structure returned will look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
   "data": [
      {
           "id": "<ROUTE INPUT ID>",
           "endpoint": {
               "platformName": "PUBNUB",
               "messageTypeId": "3d2e31bb-6a4e-4211-afbd-e4134685e77f"
           },
           "version": "2.0",
           "name": "Created Event Listener",
           "state": "ENABLED",
           "filters": [
               {
                   "field": "channel",
                   "value": "testchannel",
                   "type": "EXACT_MATCH"
               }
           ]
       }
   ],
   "meta": {
       "paging": {
           "totalElements": 1,
           "totalPages": 1,
           "pageSize": 1,
           "pageNumber": 0,
           "pageOffset": 0
       }
   }
}

Notice how the API call returns the messageTypeId and filters properties, as explained previously.

Creating the Router

We want to export messages to a Webhook, and the code to do this will look as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
curl --location 'https://admin.pubnub.com/api/ena/v2/routes/routers' \
--header 'X-Session-Token: <YOUR SESSION TOKEN>' \
--header 'X-Subscribe-Key: <YOUR SUBSCRIBE KEY>' \
--data '{
   "steps": [
       {
           "type": "ACTION",
           "name": "Webhook example",
           "configuration": {
               "url": "<YOUR WEBHOOK URL>",
               "batching": {
                   "timeLimitSeconds": 5,
                   "itemsLimit": 100,
                   "enabled": false
               },
               "outputFormat": {
                   "enveloped": true,
                   "version": "2.0"
               },
               "type": "WEBHOOK"
           }
       }
   ]
}'

The response from this API will contain the same fields as the call to GET existing Routers, explained shortly.

What if I want to create a different type of router, such as a Kafka router (action) or AWS Kinesis action?

Each Router will have its own type (e.g., EDA_KAFKA or AWS_KINESIS, for the given examples). Each Router will also have its own schema defining the required fields, but please refer to the documentation for a complete definition of the schemas for all Routers.

Retrieving existing Routers

Rather than creating the Router from scratch through the API, you might find it easier to use the Events & Actions UI to create the corresponding action in the portal and then retrieve that action through the E&A API. This will return the required schema format, which you can just copy and paste.

You can GET all routers (actions) using the following API call:

1
2
3
curl --location 'https://admin.pubnub.com/api/ena/v2/routes/routers' \
--header 'X-Session-Token: <YOUR SESSION TOKEN>' \
--header 'X-Subscribe-Key: <YOUR SUBSCRIBE KEY>' \

The returned structure will look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
   "data": [
       {
           "id": "<ROUTER ID>",
           "type": "MULTICAST",
           "steps": [
               {
                   "type": "ACTION",
                   "name": "Webhook example",
                   "configuration": {
                       "url": "<YOUR WEBHOOK URL>",
                       "batching": {
                           "timeLimitSeconds": 5,
                           "itemsLimit": 100,
                           "enabled": false
                       },
                       "outputFormat": {
                           "enveloped": true,
                           "version": "2.0"
                       },
                       "type": "WEBHOOK"
                   }
               }
           ]
       }
   ],
   "meta": {
       "paging": {
           "totalElements": 1,
           "totalPages": 1,
           "pageSize": 1,
           "pageNumber": 0,
           "pageOffset": 0
       }
   }
}

Notice how the configuration field contains the required schema for Webhooks, along with the required type.

Creating the Route

Creating a Route will connect a Route Input with a Router. In the language used to describe E&A in the portal, this is the same as associating an event listener with an action. The call looks like this:

1
2
3
4
5
6
7
8
curl --location 'https://admin.pubnub.com/api/ena/v2/routes' \
--header 'X-Session-Token: <YOUR SESSION TOKEN>' \
--header 'X-Subscribe-Key: <YOUR SUBSCRIBE KEY>' \
--header 'Content-Type: application/json' \
--data '{
 "routeInputId": "<YOUR ROUTE INPUT ID>",
 "routerId": "<YOUR ROUTER ID>"
}'

Where does the routeInputId come from?

The routeInputId is the unique identifier for the Route Input you created previously. This value is returned in the data.id field after you create the Route Input (POST /v2/routes/route-inputs) or can be found in that same field in the call to GET all Route Inputs.

The format of the ID will be a long hexadecimal string.

Where does the routerId come from?

The routerId is the unique identifier for the Router you created previously. This value is returned in the data.id field after you create the Router (POST /v2/routes/routers) or can be found in that same field in the call to GET all Routers.

The format of the ID will be a long hexadecimal string.

How do I define the Router or Route Input as part of the Create Route call?

This demo takes the simplest approach by creating the Router Input and Router beforehand, but it is possible to specify one or the other during the POST /v2/routes call. Please refer to the documentation for more information.

Not Covered in this Article

This article has covered the basics and can hopefully be a springboard for your app development.

The E&A API also supports the following, not covered in this article:

The Router and RouteInputs endpoints both support a PUT verb to modify an existing Router or Route Input. Specify all parameters since you cannot just pass the values you wish to modify.
All three endpoints also support GET and DELETE for a specific instance, e.g., GET /v2/routes/{route-id}.
Although this article only discussed the Webhook Router, the API also supports the following: Amazon SQS, Amazon Kinesis, Amazon S3, Apache Kafka, IFTT Webhook, AMQP. This list is currently accurate but will expand in the future.

Get Access

At the time of writing, access to the E&A API is only available on request. Please use this form to request access. Full documentation will be provided after your request is approved. If you have any questions, please reach out to the developer relations team at devrel@pubnub.com or our support team

How to Use the Events & Actions API