Legacy webhooks migration guide
Some PubNub features send events (Presence, Mobile Push, Message Persistence). You can forward these events to webhooks for analysis.
Previously, you configured webhooks on the Keysets page in Admin Portal. You now send webhooks with Events & Actions.
This change gives you more flexibility. You can tie multiple actions to one event and configure retries and headers.
There are two main changes:
- How the webhook payload is structured
- Where you configure webhooks
Paid and free plans
If you are already (before 16.01.2024) on a paid plan, we will migrate your existing webhooks for you.
If you use a free plan, follow these steps to manually migrate. A paid plan is required to use webhooks.
Prerequisites
Use a paid plan to access Events & Actions.
Legacy and current webhook payloads
Webhooks now use one standardized payload across event sources.
- Legacy webhook payload
- Current webhook payload
Feature | Webhook Name | Sample Event Payload |
---|---|---|
Presence | Channel 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" } |
Presence | Channel 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" } |
Presence | Presence 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" } |
Presence | Presence 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" } |
Presence | Presence 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" } |
Presence | Presence 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" } |
Presence | Presence 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 Notifications | Push 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 Notifications | Push 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 } |
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-576a47bb0658","channel":"CHANNEL-NAME","timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE"}]} |
Presence | Channel Inactive Webhook | {"schema":"pubnub.com/schemas/events/presence.channel.state.inactive?v=1.0.0","data":[{"id":"1d558c0f-576a47bb0658","channel":"CHANNEL-NAME","timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE"}]} |
Presence | Presence Join Webhook | {"schema":"pubnub.com/schemas/events/presence.user.channel.joined?v=1.0.0","data":[{"id":"1d558c0f-576a47bb0658","channel":"CHANNEL-NAME","userId":"5934fbc6-bf06b3c3b365","occupancy":3,"data":{},"timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE"}]} |
Presence | Presence Leave Webhook | {"schema":"pubnub.com/schemas/events/presence.user.channel.left?v=1.0.0","data":[{"id":"1d558c0f-576a47bb0658","channel":"CHANNEL-NAME","userId":"5934fbc6-bf06b3c3b365","occupancy":3,"data":{},"timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE"}]} |
Presence | Presence Timeout Webhook | {"schema":"pubnub.com/schemas/events/presence.user.timedout.in.channel?v=1.0.0","data":[{"id":"1d558c0f-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 | {"schema":"pubnub.com/schemas/events/presence.channel.user.state.in.changed?v=1.0.0","data":[{"id":"1d558c0f-576a47bb0658","channel":"CHANNEL-NAME","userId":"5934fbc6-bf06b3c3b365","occupancy":3,"data":{},"timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE"}]} |
Presence | Presence Interval Webhook | {"schema":"pubnub.com/schemas/events/presence.channel.occupancy.counted?v=1.0.0","data":[{"id":"1d558c0f-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 | {"schema":"pubnub.com/schemas/events/push.message.sending.failed?v=1.0.0","data":[{"id":"1d558c0f-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 | {"schema":"pubnub.com/schemas/events/push.device.removed?v=1.0.0","data":[{"id":"1d558c0f-576a47bb0658","action":"${feedback|remove|update}","device":"","platform":"APNS","timestamp":"1992-01-01T10:00:20.021Z","subKey":"SUBKEY-HERE"}]} |
Migration steps
To migrate your webhooks: