Event / Action List

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:

  • 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 be activated by a particular event, but no action will occur.

Actions per listener

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

Event source​

The event source is the primary configuration option for each listener. It narrows down the area of your application the listener reacts to. The following event sources are available:

Messages​

Event ProducerEvent TypeDescription
Pub/Sub
Message sent
Message was published on a channel.

Events & Actions doesn't process the prefix/suffix-based internal publishes (such as Presence publishes to -pnpres channels).
Message Reaction
Message reaction created
A reaction was added to a published message.
Message reaction deleted
A reaction was removed from a published message.
Files
File sent
A file was sent to a channel.

Users​

Event ProducerEvent TypeDescription
Presence
User state changed in channel
User's Presence state changed on a channel.
CRUD
User created
User metadata was set.
User updated
User metadata was changed.
User deleted
User metadata was removed.

Channels​

Event ProducerEvent TypeDescription
Presence
User started subscription to channel
User subscribed to a channel.
User stopped subscription to channel
User unsubscribed from a channel.
User timed out while subscribing to channel
User didn't successfully subscribe to a channel because of a timeout.
First user subscribed to channel
User subscribed to a channel which didn't have any subscribers (the channel's occupancy changed from 0 to 1).
Last user left channel
User left a channel which now has no remaining subscribers (the channel's occupancy changed from 1 to 0).
Interval occupancy counted
Channel reported its current occupancy and user deltas at the configured interval.
CRUD
Channel created
Channel metadata was set.
Channel updated
Channel metadata was changed.
Channel deleted
Channel metadata was removed.

Mobile Push notifications​

Event ProducerEvent TypeDescription
Devices
Device removed
Device token was removed from a channel.
Push error
Mobile Push notification error was thrown.

Memberships​

Event ProducerEvent TypeDescription
CRUD
Membership created
Membership metadata was set.
Membership updated
Membership metadata was changed.
Membership deleted
Membership metadata was removed.

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
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​
NameDescription
Exact Match
Trigger an action only if there is an exact match.
Contains
Trigger 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.

Settings​

There are certain configurable options shared across all action types:

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)

Retries​

Each action supports a request retry feature which follows a jittered retry strategy. This means that a new, random delay is computed for each retry attempt, which is generated according to the following formula:

delay = random_between(minIntervalForRetry = 10sec, min(maxRetryPeriod = 900sec, (baseRetryIntervalDefinedByUser * 2)^ attemptNo))

This approach minimizes the impact on the endpoint and the "healthy" traffic, reducing the risk of overload (and, as a result, additional failures), while the repeated retries are executed.

Envelope​

You can choose whether the payload schema should contain detailed E&A JSON metadata. We refer to this metadata as an envelope. It is helpful if there is data outside the event payload you want to use, like what channel it was sent to or which listener triggered it.

We recommend not including the envelope if you're only interested in the actual event payload and want to avoid storing redundant information.

Every action supports wrapping the payload in an envelope. There are three payload schema versions: 1.0, 2.0, and 2.1 which is the default. Each version has two variants:

{
    "event": {
        "channel": "Channel-Barcelona",
        "eventCategory": "message",
        "eventType": "message.publish",
        "eventId": "83aa8051-bf51-4825-aafd-84682456116f",
        "eventPayload": {
            "message": "Enter message here",
            "meta": null
        },
        "iso8601timestamp": "2024-01-18T08:26:48Z",
        "subscribeKey": "6f65629a-6220-4ecb-87f2-b2c6f142cd66",
        "timetoken": "17055664085783523",
        "senderId": "Jack-device"
    },
show all 33 lines

By default, all actions use the 2.1 version of the payload schema with no envelope. When you turn on the Is Enveloped toggle in the UI, you can select which payload schema version to use.

is enveloped toggle and drop-down list

You can set the following retry policy for each action:

NameDescriptionDefault valueMin valueMax value
Number of retries
Number of attempts to retry the action
2
1
4
Retry interval (in seconds)
Dynamically set a delay between retry attempts based on exponential backoff influenced by user-defined parameters and randomness
450
10
900

Batching​

The Amazon S3 and Webhook actions support batching, which lets you manage a large volume of events by sending multiple events together in a single request, rather than sending each event individually.

Batching is recommended to minimize costs associated with PUT operations. Without batching, each message is stored individually, leading to increased expenses. However, potential drawbacks, such as the need to extract individual events from the batch file, must be considered.

For the Amazon S3 action, if your batch exceeds 5MB, it is divided into multiple parts and uploaded to the S3 storage in chunks. For more details on multipart upload, check the Amazon docs.

For the Webhook action, the choice of storage or a batch size limit depends on your application architecture, system requirements, and implementation.

If you want to enable Batching on an action, you must set both of these options:

NameDescriptionDefault valueMin valueMax value
Item count bound
Maximum number of messages to be queued per batch
100
1
10000
Time bound (in seconds)
Time window during which individual data points or events are collected into a single batch
5
1
300

A batch will be sent based on the number of messages in the queue or time, depending on which limit is reached first.

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.

Webhook retries​

The Webhook action supports up to four request retries with a configurable retry interval. However, certain conditions for retrying webhooks depend on the HTTP status. If E&A receives a 2XX status as a result of the Webhook action, the webhook isn't retried as the operation was successful. If a 301 is received, the webhook follows up to three redirects before failing. Any other statuses are retried according to the retry policy set within the action.

Webhook retries

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

Webhook Payload​

Our webhooks use a standardized payload structure regardless of the event source.

FeatureWebhook NameSample Event Payload
Presence
Channel Active Webhook
{"schema":"pubnub.com/schemas/events/presence.channel.state.active?v=1.0.0","data":[{"id":"1d558c0f-78d8-576a47bb0658","timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE","channel":"CHANNEL-NAME"}]}
Presence
Channel Inactive Webhook
{"schema":"pubnub.com/schemas/events/presence.channel.state.inactive?v=1.0.0","data":[{"id":"1d558c0f-78d8-576a47bb0658","timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE","channel":"CHANNEL-NAME"}]}
Presence
Presence Join Webhook
{"schema":"pubnub.com/schemas/events/presence.user.channel.joined?v=1.0.0","data":[{"id":"1d558c0f-78d8-576a47bb0658","channel":"CHANNEL-NAME","userId":"5934fbc6-bf06b3c3b365","occupancy":3,"data":{},"timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE"}]}
Presence
Presence Leave Webhook
{"schema":"pubnub.com/schemas/events/presence.user.channel.left?v=1.0.0","data":[{"id":"1d558c0f-78d8-576a47bb0658","channel":"CHANNEL-NAME","userId":"5934fbc6-bf06b3c3b365","occupancy":3,"data":{},"timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE"}]}
Presence
Presence Timeout Webhook
{"schema":"pubnub.com/schemas/events/presence.user.timedout.in.channel?v=1.0.0","data":[{"id":"1d558c0f-78d8-576a47bb0658","channel":"CHANNEL-NAME","userId":"5934fbc6-bf06b3c3b365","occupancy":3,"data":{},"timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE"}]}
Presence
Presence State Change Webhook
{"schema":"pubnub.com/schemas/events/presence.channel.user.state.in.changed?v=1.0.0","data":[{"id":"1d558c0f-78d8-576a47bb0658","channel":"CHANNEL-NAME","userId":"5934fbc6-bf06b3c3b365","occupancy":3,"data":{},"timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE"}]}
Presence
Presence Interval Webhook
{"schema":"pubnub.com/schemas/events/presence.channel.occupancy.counted?v=1.0.0","data":[{"id":"1d558c0f-78d8-576a47bb0658","channel":"CHANNEL-NAME","occupancy":"3","timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE","usersJoined":["id-1","id-2"],"usersLeft":["id-1","id-2"],"usersTimedout":["id-5","id-6"]}]}
Mobile Push Notifications
Push Error Webhook
{"schema":"pubnub.com/schemas/events/push.message.sending.failed?v=1.0.0","data":[{"id":"1d558c0f-78d8-576a47bb0658","channel":"CHANNEL-NAME","devices":"","platform":"APNS","timestamp":"1992-01-01T10:00:20.021Z","state":"error","subKey":"SUBKEY-HERE","payload":"ERROR MESSAGE"}]}
Mobile Push Notifications
Push Device Removed Webhook
{"schema":"pubnub.com/schemas/events/push.device.removed?v=1.0.0","data":[{"id":"1d558c0f-78d8-576a47bb0658","action":"${feedback|remove|update}","device":"","platform":"APNS","timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE"}]}

For information on the payload structure of legacy webhooks and how to migrate to the latest version, refer to the migration guide.

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.

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

Amazon Kinesis configuration

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

Amazon S3​

Events & Actions supports uploading data to Amazon S3, a simple storage service that handles storing and retrieving any amount of data.

Amazon S3 configuration

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

Apache Kafka​

Events & Actions supports exporting events to the Apache Kafka event streaming platform.

Kafka configuration

To use Events & Actions with Apache Kafka, you must first configure your Apache Kafka environment.

IFTTT Webhook​

Events & Actions supports exporting events to the IFTTT service.

IFTTT configuration

To use Events & Actions with IFTTT, you must first configure your IFTTT environment.

AMQP​

Events & Actions supports exporting events to the Advanced Message Queuing Protocol (AMQP).

AMQP configuration

To use Events & Actions with AMQP, you must first configure your AMQP environment.

Last updated on
On this page