Event / Action List

Event listeners wait for PubNub events. When an event occurs, the listener runs. In Events & Actions (E&A), 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 listener can trigger several actions. For example, when a client with User ID thomas_anderson publishes a message, PubNub runs all actions attached to that 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 actions still activates, but no action runs.

Actions per listener

Your Events & Actions tier sets how many actions a listener can trigger.

Event source

The event source is the main setting for each listener. It narrows where the listener reacts. Available sources:

• Messages
• Users
• Channels
• Mobile Push notifications
• Membership

Messages

Event Producer	Event Type	Description
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 Producer	Event Type	Description
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 Producer	Event Type	Description
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 Producer	Event Type	Description
Devices	Device removed	Device token was removed from a channel.
	Push error	Mobile Push notification error was thrown.

Memberships

Event Producer	Event Type	Description
CRUD	Membership created	Membership metadata was set.
	Membership updated	Membership metadata was changed.
	Membership deleted	Membership metadata was removed.

Payloads

For complete payload examples and field descriptions, see Events & Actions Payloads.

Filters

Filters define when actions run. Choose one of:

• No Filter
• Basic Filters
• Advanced JSON path

For any filter (except No filter), choose which message part to parse. Advanced JSON path is most flexible and can inspect many payload fields.

No filter

No filter triggers actions for all messages on the keyset.

Basic filters

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

Filters

Name	Description
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

Name	Description
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

Enter the string value to match.

Advanced JSON path

Use JSONPath to search your message payload. All PubNub events follow a schema that JSONPath can query.

To filter messages containing Wake up, Neo..., use: $.message[?(@.text contains "Wake up, Neo...")]. This finds any message text with that phrase.

Examples:

Match on	JSON 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')]

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 send data when a listener is triggered. Configure a Webhook or use Amazon SQS or Kinesis.

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:

• Retries
• Envelope
• Batching

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 spreads retries and reduces load on your endpoint while keeping traffic healthy.

Envelope

You can include E&A JSON metadata in the payload (the “envelope”). Use it when you need data outside the event payload, like the channel or which listener triggered it.

Skip the envelope if you only need the event payload and want to avoid extra fields.

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: enveloped and unenveloped.

Payloads

For envelope formats and full schemas, see Events & Actions Payloads.

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.

You can set the following retry policy for each action:

Name	Description	Default value	Min value	Max 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 helps reduce PUT costs by sending many events at once. Consider the tradeoff: you may need to extract individual events from a batch file.

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:

Name	Description	Default value	Min value	Max 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 integrate E&A with third‑party systems for event‑driven data flow. Configure the receiving endpoint and, if needed, 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 are available on paid tiers.

Webhook payload

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

Feature	Webhook Name	Sample 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" } ] } View Payload
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" } ] } View Payload
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" } ] } View Payload
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" } ] } View Payload
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" } ] } View Payload
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" } ] } View Payload
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", show all 24 lines View Payload
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" } ] } View Payload
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" } ] } View Payload

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

First, configure the connection 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

First, configure the connection 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

First, configure the connection between PubNub and AWS.

Apache Kafka

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

Kafka configuration

First, configure your Apache Kafka environment.

IFTTT webhook

Events & Actions supports exporting events to the IFTTT service.

IFTTT configuration

First, configure your IFTTT environment.

AMQP

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

AMQP configuration

First, configure your AMQP environment.