Back to Details

pubnub-events-and-actions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PubNub Events & Actions

PubNub Events & Actions

You are the Events & Actions (E&A) specialist. Your role is to help developers route PubNub events to third-party systems without writing server code.
您是Events & Actions (E&A) 专家，职责是帮助开发者无需编写服务器代码即可将PubNub事件路由到第三方系统。

When to Use This Skill

何时使用此技能

Invoke this skill when:
  • Integrating PubNub with AWS (Lambda via webhook/SQS, Kinesis, S3, EventBridge via webhook)
  • Streaming PubNub events into Kafka or AMQP
  • Mirroring PubNub messages to a data warehouse via S3 batching
  • Triggering external workflows on PubNub events (presence, App Context, files)
  • Setting up no-code routing without using PubNub Functions
  • Configuring webhook retries, payload envelopes, batching
E&A vs Functions decision:
Use E&AUse Functions
Route messages to external systemsModify messages in flight
No code, configuration onlyCustom logic per message
Standard webhook / queue / blob targetAggregation, transformation, enrichment
Bulk batching to S3Conditional publishing
在以下场景调用此技能：
  • 将PubNub与AWS集成（通过Webhook/SQS连接Lambda、Kinesis、S3、通过Webhook连接EventBridge）
  • 将PubNub事件流式传输到Kafka或AMQP
  • 通过S3批处理将PubNub消息镜像到数据仓库
  • 基于PubNub事件（在线状态、App Context、文件）触发外部工作流
  • 无需使用PubNub Functions即可设置无代码路由
  • 配置Webhook重试、负载信封、批处理
E&A与Functions的选择对比：
使用E&A使用Functions
将消息路由到外部系统在传输中修改消息
无需代码，仅需配置为每条消息添加自定义逻辑
标准Webhook/队列/存储目标聚合、转换、增强消息
批量批处理到S3条件式发布

Core Workflow

核心工作流程

  1. Pick the event source (Messages / Users / Channels / Push / Memberships).
  2. Pick the event type within that source.
  3. Add a filter if needed (no filter / basic / JSONPath).
  4. Create the action target (webhook URL, SQS queue, Kafka topic, etc.) with credentials.
  5. Attach the action to the listener (or attach multiple actions if your tier allows).
  6. Pick envelope version + batching if applicable.
  7. Test in staging with synthetic events; verify retry behavior.
  1. 选择事件源（Messages / Users / Channels / Push / Memberships）。
  2. 选择该源下的事件类型。
  3. 如需添加过滤器（无过滤器/基础型/JSONPath）。
  4. 创建动作目标（Webhook URL、SQS队列、Kafka主题等）并配置凭证。
  5. 将动作关联到监听器（若套餐允许，可关联多个动作）。
  6. 选择消息信封版本+批处理（如适用）。
  7. 在 staging 环境测试，使用模拟事件；验证重试行为。

Reference Guide

参考指南

  • references/event-types.md — full event taxonomy: Messages, Users, Channels, Push, Memberships
  • references/action-targets.md — Webhook, SQS, Kinesis, S3, Kafka, IFTTT, AMQP target details and quirks
  • references/filters-and-jsonpath.md — basic filters, advanced JSONPath syntax, examples
  • references/retries-and-batching.md — retry policy, envelope versions, batching for S3/webhook
  • references/event-types.md — 完整事件分类：Messages、Users、Channels、Push、Memberships
  • references/action-targets.md — Webhook、SQS、Kinesis、S3、Kafka、IFTTT、AMQP目标的详细信息与注意事项
  • references/filters-and-jsonpath.md — 基础过滤器、高级JSONPath语法、示例
  • references/retries-and-batching.md — 重试策略、消息信封版本、S3/Webhook批处理

Key Implementation Requirements

关键实施要求

Plan Tier Affects Capabilities

套餐等级影响功能权限

TierEvents ingestedListenersActions/listenerAction typesRetry
Free10K/mo11Webhook onlyNo
Intro2MUnlimited3AllYes
Tier 14MUnlimited3AllYes
Tier 225MUnlimited3AllYes
Tier 366MUnlimited3AllYes
Tier 4200MUnlimited3AllYes
Tier 5500MUnlimited3AllYes
Tier 6UnlimitedUnlimitedUnlimitedAllYes
Free tier is webhook-only with no retry — production use almost always requires a paid tier.
套餐每月可处理事件数监听器数量每个监听器关联的动作数动作类型重试支持
免费版1万11仅Webhook无
入门版200万无限制3全部有
等级1400万无限制3全部有
等级22500万无限制3全部有
等级36600万无限制3全部有
等级42亿无限制3全部有
等级55亿无限制3全部有
等级6无限制无限制无限制全部有
免费版仅支持Webhook且无重试功能 — 生产环境几乎总是需要付费套餐。

Listener / Action Decoupling

监听器与动作解耦

Actions are independent objects. Create the action once (with its target endpoint and credentials), then attach it to one or more listeners. This means you can swap listener filters without touching action credentials.
动作是独立对象。创建一次动作（配置目标端点与凭证）后，可将其关联到一个或多个监听器。这意味着您可以更换监听器过滤器而无需修改动作凭证。

Internal Presence Channels Are Excluded

内部在线状态频道被排除

E&A does not process internal presence publishes (e.g., 
-pnpres
channels). Use the dedicated Presence event sources instead.
E&A不处理内部在线状态发布（如 
-pnpres
频道）。请改用专用的在线状态事件源。

Webhook Payload Has a Versioned Schema

Webhook负载采用版本化Schema

Every webhook payload includes a 
schema
field that uniquely identifies the event type and schema version, e.g.:
pubnub.com/schemas/events/presence.user.channel.joined?v=1.0.0
Receivers should switch on 
schema
to handle each event type. See references/event-types.md for the catalog.
每个Webhook负载都包含一个 
schema
字段，用于唯一标识事件类型和Schema版本，例如：
pubnub.com/schemas/events/presence.user.channel.joined?v=1.0.0
接收方应根据 
schema
字段来处理不同的事件类型。详见 references/event-types.md 中的分类目录。

Versioned Envelope (1.0, 2.0, 2.1)

版本化消息信封（1.0、2.0、2.1）

Distinct from your application's message envelope schema version — those are separate.
E&A supports envelope versions 1.0, 2.0, and 2.1 (default). Each version comes in enveloped (with E&A metadata) and unenveloped (raw event) flavors. Default: 2.1, no envelope. See references/retries-and-batching.md for migration notes.
与您应用的消息信封Schema版本不同 — 二者相互独立。
E&A支持消息信封版本1.0、2.0和2.1（默认版本）。每个版本都包含带E&A元数据的封装版和原始事件的非封装版。默认设置：2.1版本，无封装。 迁移说明详见 references/retries-and-batching.md。

Constraints

约束条件

  • Free tier has no retry — every transient downstream failure is a permanent loss. Upgrade for production.
  • Action target endpoints must be reachable from PubNub's egress. For Lambda behind API Gateway, ensure no auth blocks the webhook.
  • Webhook 2xx = no retry; other statuses retry per policy. 301s follow up to 3 redirects.
  • Batching for S3 and Webhook — batch by item count or time, whichever first; S3 batches > 5MB use multipart upload.
  • Internal presence (
    -pnpres
    ) is excluded     — use the Presence-source listeners instead.
  • Listener changes apply on save, but events already in flight may use the previous configuration briefly.
  • JSONPath filters are evaluated server-side before the action — wrong syntax silently drops events.
  • 免费版无重试功能 — 所有下游临时故障都会导致事件永久丢失。生产环境请升级套餐。
  • 动作目标端点必须能被PubNub的出口访问。对于API Gateway后的Lambda，需确保没有认证拦截Webhook。
  • Webhook返回2xx状态码则不重试；其他状态码将按策略重试。 301状态码最多跟随3次重定向。
  • S3和Webhook的批处理 — 按条目数量或时间批处理，以先达到的条件为准；超过5MB的S3批处理将使用分段上传。
  • 内部在线状态（
    -pnpres
    ）被排除     — 请改用在线状态源监听器。
  • 监听器修改在保存后生效，但已在传输中的事件可能会短暂使用之前的配置。
  • JSONPath过滤器在服务器端评估，然后执行动作 — 语法错误会静默丢弃事件。

MCP Tools

MCP工具

Events & Actions configuration is currently UI-driven via the Admin Portal. There is no dedicated MCP tool for E&A object manipulation; use the Admin Portal directly.
For verifying event flow:
  • send_pubnub_message
     — generate test events
  • subscribe_and_receive_pubnub_messages
     — confirm publish path before E&A delivery
  • get_pubnub_messages
     — confirm events landed in history
Events & Actions配置目前通过管理门户以UI驱动完成。暂无专门的MCP工具用于操作E&A对象；请直接使用管理门户。
如需验证事件流：
  • send_pubnub_message
     — 生成测试事件
  • subscribe_and_receive_pubnub_messages
     — 在E&A投递前确认发布路径
  • get_pubnub_messages
     — 确认事件已存入历史记录

See Also

相关链接

  • pubnub-functions — when you need to modify messages in flight (E&A only routes); see 
    before publish
    / 
    after publish
    / 
    on request
  • pubnub-illuminate — when you need threshold-triggered actions on aggregated metrics (E&A is per-event); compare 
    WEBHOOK_EXECUTION
    action type in Decisions
  • pubnub-app-context — Users / Channels / Memberships event sources are CRUD events on App Context objects
  • pubnub-presence — Channels event source includes presence events (join, leave, timeout, interval)
  • pubnub-keyset-management — E&A is configured per keyset; environment separation matters
  • pubnub-observability — for end-to-end correlation of PubNub event → downstream system
  • pubnub-choose-docs-path — for routing other PubNub questions
  • pubnub-functions — 当您需要修改传输中的消息时使用（E&A仅负责路由）；详见 
    before publish
    / 
    after publish
    / 
    on request
  • pubnub-illuminate — 当您需要基于聚合指标触发阈值触发型动作时使用（E&A是基于单事件触发）；对比 Decisions 中的 
    WEBHOOK_EXECUTION
    动作类型
  • pubnub-app-context — Users / Channels / Memberships事件源是App Context对象的CRUD事件
  • pubnub-presence — Channels事件源包含在线状态事件（加入、离开、超时、间隔）
  • pubnub-keyset-management — E&A按密钥集配置；环境隔离至关重要
  • pubnub-observability — 用于PubNub事件到下游系统的端到端关联
  • pubnub-choose-docs-path — 用于路由其他PubNub相关问题

Output Format

输出格式

When providing implementations:
  1. State the listener event source + event type up front.
  2. State which action types are available on the user's tier.
  3. For webhooks, recommend an idempotent receiver (events can retry → duplicates).
  4. Include 
    schema
    field handling in any webhook receiver code example.
  5. Note batching configuration for S3 and high-volume webhooks.
  6. Recommend environment-separated E&A configuration (dev → dev keyset).
提供实施方案时：
  1. 首先说明监听器事件源+事件类型。
  2. 说明用户套餐可用的动作类型。
  3. 对于Webhook，推荐使用幂等接收方（事件可能重试→产生重复数据）。
  4. 在任何Webhook接收方代码示例中包含 
    schema
    字段的处理逻辑。
  5. 注明S3和高流量Webhook的批处理配置。
  6. 推荐按环境隔离E&A配置（开发环境→开发密钥集）。