Legacy webhooks migration guide

Some PubNub features that send events (Presence, Mobile Push Notifications, and Message Persistence) have configurable webhooks to which you can forward those events for data collection and analysis.

Webhooks used to be configurable on the Keysets page in Admin Portal. That is no longer the case as we moved the functionality of sending webhooks to Events & Actions.

With this change, we provide greater flexibility for sending your data outside PubNub, allowing you to tie multiple actions to one event and configure retries and headers.

There are two main changes:

If you are already (before 16.01.2024) on a paid plan, we will migrate your existing webhooks for you.

If you're a free plan user, read on to understand how to manually migrate your webhooks so that they use the latest webhook payload. You will still need to purchase a paid plan to use webhooks.


You must purchase a paid plan to use Events & Actions.

Legacy and current webhook payloads

We have introduced webhooks that use a standardized payload structure regardless of the event source.

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

Legacy webhooks

Migration steps

To migrate your existing webhooks:

  1. Create an event listener by following these steps.
  2. Add a Webhook action and configure it accordingly by following these steps.
  3. Repeat for each legacy webhook you had configured and want to continue receiving(Presence, Mobile Push Notifications, and Message Persistence).
Last updated on