---
source_url: https://www.pubnub.com/docs/serverless/events-and-actions/events
title: Event / Action List
updated_at: 2026-05-21T15:48:09.294Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


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

:::note 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](https://www.pubnub.com/docs/general/setup/users-and-devices#set-the-user-id).
:::

A listener with no actions still activates, but no action runs.

:::tip Actions per listener
Your [Events & Actions tier](https://www.pubnub.com/docs/serverless/events-and-actions/overview#availability) 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](#messages)
* [Users](#users)
* [Channels](#channels)
* [Mobile Push notifications](#mobile-push-notifications)
* [Membership](#memberships)

### Messages

| Event Producer | Event Type | Description |
| --- | --- | --- |
| `Pub/Sub` | `Message sent` | Message was [published](https://www.pubnub.com/docs/general/messages/publish) on a channel. Events & Actions doesn't process the prefix/suffix-based internal publishes (such as Presence publishes to [-pnpres channels](https://www.pubnub.com/docs/general/presence/presence-events#subscribe-to-presence-channel)). |
| `Message Reaction` | `Message reaction created` | A [reaction](https://www.pubnub.com/docs/general/messages/actions) was added to a published message. |
|  | `Message reaction deleted` | A reaction was removed from a published message. |
| `Files` | `File sent` | A [file](https://www.pubnub.com/docs/general/files#send-files) was sent to a channel. |

### Users

| Event Producer | Event Type | Description |
| --- | --- | --- |
| `Presence` | `User state changed in channel` | User's [Presence](https://www.pubnub.com/docs/general/presence/presence-state) state changed on a channel. |
| `CRUD` | `User created` | [User metadata](https://www.pubnub.com/docs/general/metadata/users-metadata) was set. |
|  | `User updated` | User metadata was changed. |
|  | `User deleted` | User metadata was removed. |

###### React to user lifecycle changes

User events fire when [App Context user metadata](https://www.pubnub.com/docs/general/metadata/users-metadata) is created, updated, or deleted. Each event identifies the affected user by their [User ID](https://www.pubnub.com/docs/general/setup/users-and-devices). Pair these events with actions to synchronize external systems, notify administrators, or trigger downstream workflows whenever a user profile changes.

### 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](https://www.pubnub.com/docs/general/presence/presence-events#presence-event-modes). |
| `CRUD` | `Channel created` | [Channel metadata](https://www.pubnub.com/docs/general/metadata/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](https://www.pubnub.com/docs/general/push/send#register-devices) was removed from a channel. |
|  | `Push error` | Mobile Push notification [error](https://www.pubnub.com/docs/general/push/mobile-push-troubleshooting) was thrown. |

### Memberships

| Event Producer | Event Type | Description |
| --- | --- | --- |
| `CRUD` | `Membership created` | [Membership metadata](https://www.pubnub.com/docs/general/metadata/membership-metadata) was set. |
|  | `Membership updated` | Membership metadata was changed. |
|  | `Membership deleted` | Membership metadata was removed. |

###### React to membership lifecycle events

Membership events fire when users are added to or removed from channels through [App Context membership operations](https://www.pubnub.com/docs/general/metadata/membership-metadata). Use these events to synchronize external systems, notify channel members, or trigger downstream workflows whenever the membership roster changes. Membership data persists until explicitly deleted, so these events represent durable state changes rather than ephemeral signals.

:::note Payloads
For complete payload examples and field descriptions, see [Events & Actions Payloads](https://www.pubnub.com/docs/serverless/events-and-actions/ena-payloads).
:::

### Filters

Filters define when actions run. Choose one of:

* [No Filter](#no-filter)
* [Basic Filters](#basic-filters)
* [Advanced JSON path](#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](https://github.com/json-path/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'])]` |
| Sender ID | `$.[?(@.uuid == 'thomas_anderson')]` |
| Exclude specific channels | `$.[?(@.channel nin ['internal', 'debug'])]` |
| Either condition (OR) | `$.[?(@.meta.sensor == 'warn' || @.meta.sensor == 'alert')]` |
| Combination of fields (AND) | `$.[?(@.channel =~ /.*some_suffix/i && @.meta.sensor_reading > 25 && @.message.status != 'error')]` |

Try your JSONPath expression:

JSON Payload
{
  "meta": {
    "sensor": "warn",
    "sensor_reading": 30
  },
  "message": {
    "text": "Wake up, Neo...",
    "status": "ok",
    "some_property": "some_value"
  },
  "channel": "my_channel.some_suffix",
  "uuid": "thomas_anderson"
}
✓
Valid JSON
JSONPath Expression
✓
Valid expression
Event JSON schema

##### Message publish​

```json
{
    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](https://aws.amazon.com/sqs/) or [Kinesis](https://aws.amazon.com/kinesis/).

:::tip Actions per listener
The number of actions a single event listener may trigger depends on your [Events & Actions tier](https://www.pubnub.com/docs/serverless/events-and-actions/overview#availability).
:::

### Settings

There are certain configurable options shared across all action types:

* [Retries](#retries)
* [Envelope](#envelope)
* [Batching](#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:

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

:::note Payloads
For envelope formats and full schemas, see [Events & Actions Payloads](https://www.pubnub.com/docs/serverless/events-and-actions/ena-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.

![is enveloped toggle and drop-down list](https://www.pubnub.com/assets/images/enveloping-9a85031a1f14c05ea176f6e533fe6453.png)

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](https://www.pubnub.com/docs/serverless/events-and-actions/actions/create-s3-action) and [Webhook](https://www.pubnub.com/docs/serverless/events-and-actions/actions/create-webhook-action) 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html#mpu-process). 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.

:::note Webhook retries
Webhook retries are available on paid tiers.
:::

#### Webhook payload

Our webhooks use a standardized payload structure regardless of the event source. The payload you receive depends on the [envelope](https://www.pubnub.com/docs/serverless/events-and-actions/events#envelope) option selected — there is one no-envelope format and several enveloped versions. The table below shows the no-envelope payload (the default).

For all versions, see [Events & Actions Payloads](https://www.pubnub.com/docs/serverless/events-and-actions/ena-payloads).

| Feature | Webhook name | No-envelope payload |
| --- | --- | --- |
| Presence | [Channel Active Webhook](https://www.pubnub.com/docs/serverless/events-and-actions/ena-payloads#first-user-subscribed-to-channel) | View Payload{ "dataSchema": "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](https://www.pubnub.com/docs/serverless/events-and-actions/ena-payloads#last-user-left-channel) | View Payload{ "dataSchema": "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](https://www.pubnub.com/docs/serverless/events-and-actions/ena-payloads#user-started-subscription-to-channel) | View Payload{ "dataSchema": "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](https://www.pubnub.com/docs/serverless/events-and-actions/ena-payloads#user-stopped-subscription-to-channel) | View Payload{ "dataSchema": "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](https://www.pubnub.com/docs/serverless/events-and-actions/ena-payloads#user-timed-out-while-subscribing-to-channel) | View Payload{ "dataSchema": "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](https://www.pubnub.com/docs/serverless/events-and-actions/ena-payloads#user-state-changed-in-channel) | View Payload{ "dataSchema": "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](https://www.pubnub.com/docs/serverless/events-and-actions/ena-payloads#interval-occupancy-counted) | View Payload{ "dataSchema": "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](https://www.pubnub.com/docs/serverless/events-and-actions/ena-payloads#push-error) | View Payload{ "dataSchema": "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](https://www.pubnub.com/docs/serverless/events-and-actions/ena-payloads#device-removed) | View Payload{ "dataSchema": "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](https://www.pubnub.com/docs/general/resources/migration-guides/legacy-webhooks-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.

:::note Amazon SQS configuration
First, [configure the connection](https://www.pubnub.com/docs/serverless/events-and-actions/actions/create-sqs-action) 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.

:::note Amazon Kinesis configuration
First, [configure the connection](https://www.pubnub.com/docs/serverless/events-and-actions/actions/create-kinesis-action) 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.

:::note Amazon S3 configuration
First, [configure the connection](https://www.pubnub.com/docs/serverless/events-and-actions/actions/create-s3-action) between PubNub and AWS.
:::

### Apache Kafka

Events & Actions supports exporting events to the [Apache Kafka](https://kafka.apache.org/) event streaming platform.

:::note Kafka configuration
First, [configure](https://www.pubnub.com/docs/serverless/events-and-actions/actions/create-kafka-action) your Apache Kafka environment.
:::

### IFTTT webhook

Events & Actions supports exporting events to the [IFTTT](https://ifttt.com/) service.

:::note IFTTT configuration
First, [configure](https://www.pubnub.com/docs/serverless/events-and-actions/actions/create-ifttt-action) your IFTTT environment.
:::

### AMQP

Events & Actions supports exporting events to the [Advanced Message Queuing Protocol (AMQP)](https://www.cloudamqp.com/blog/what-is-amqp-and-why-is-it-used-in-rabbitmq.html).

:::note AMQP configuration
First, [configure](https://www.pubnub.com/docs/serverless/events-and-actions/actions/create-amqp-action) your AMQP environment.
:::

## Terms in this document

* **PubNub** - PubNub is a real-time messaging platform that provides APIs and SDKs for building scalable applications. It handles the complex infrastructure of real-time communication, including: Message delivery and persistence, Presence detection, Access control, Push notifications, File sharing, Serverless processing with Functions and Events & Actions, Analytics and monitoring with BizOps Workspace, AI-powered insights with Illuminate.
* **User** - An individual or entity that interacts with a system, application, or service. In PubNub, a user typically refers to someone who sends or receives messages through the platform, identified by a unique user ID or username.
* **User ID** - UTF-8 encoded, unique string of up to 92 characters used to identify a single client (end user, device, or server) that connects to PubNub.