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.
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&A | Use Functions |
|---|
| Route messages to external systems | Modify messages in flight |
| No code, configuration only | Custom logic per message |
| Standard webhook / queue / blob target | Aggregation, transformation, enrichment |
| Bulk batching to S3 | Conditional publishing |
Core Workflow
- Pick the event source (Messages / Users / Channels / Push / Memberships).
- Pick the event type within that source.
- Add a filter if needed (no filter / basic / JSONPath).
- Create the action target (webhook URL, SQS queue, Kafka topic, etc.) with credentials.
- Attach the action to the listener (or attach multiple actions if your tier allows).
- Pick envelope version + batching if applicable.
- Test in staging with synthetic events; verify retry behavior.
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
Key Implementation Requirements
Plan Tier Affects Capabilities
| Tier | Events ingested | Listeners | Actions/listener | Action types | Retry |
|---|
| Free | 10K/mo | 1 | 1 | Webhook only | No |
| Intro | 2M | Unlimited | 3 | All | Yes |
| Tier 1 | 4M | Unlimited | 3 | All | Yes |
| Tier 2 | 25M | Unlimited | 3 | All | Yes |
| Tier 3 | 66M | Unlimited | 3 | All | Yes |
| Tier 4 | 200M | Unlimited | 3 | All | Yes |
| Tier 5 | 500M | Unlimited | 3 | All | Yes |
| Tier 6 | Unlimited | Unlimited | Unlimited | All | Yes |
Free tier is webhook-only with no retry — production use almost always requires a paid tier.
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.,
channels). Use the dedicated
Presence event sources instead.
Webhook Payload Has a Versioned Schema
Every webhook payload includes a
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
to handle each event type. See
references/event-types.md for the catalog.
Versioned Envelope (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.
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 () 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.
MCP Tools
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:
- — generate test events
subscribe_and_receive_pubnub_messages
- — confirm events landed in history
See Also
- pubnub-functions — when you need to modify messages in flight (E&A only routes); see / /
- pubnub-illuminate — when you need threshold-triggered actions on aggregated metrics (E&A is per-event); compare 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
Output Format
When providing implementations:
- State the listener event source + event type up front.
- State which action types are available on the user's tier.
- For webhooks, recommend an idempotent receiver (events can retry → duplicates).
- Include field handling in any webhook receiver code example.
- Note batching configuration for S3 and high-volume webhooks.
- Recommend environment-separated E&A configuration (dev → dev keyset).