---
source_url: https://www.pubnub.com/docs/general/resources/migration-guides/legacy-webhooks-migration-guide
title: Legacy webhooks migration guide
updated_at: 2026-06-19T11:36:05.521Z
---

> 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


# 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](https://www.pubnub.com/docs/serverless/events-and-actions/overview).

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](#legacy-and-current-webhook-payloads) is structured
* Where you [configure webhooks](#migration-steps)

## Paid and free plans

If you are already (before 16.01.2024) on a [paid plan](https://www.pubnub.com/pricing/), 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](https://www.pubnub.com/pricing/) to access Events & Actions.

## Legacy and current webhook payloads

Webhooks now use one standardized payload across event sources.

### Legacy 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 }` |

![Admin Portal legacy webhooks listing for Presence and Push](https://www.pubnub.com/assets/images/legacy-webhooks-175c754d56d055dc5d63855b54593580.png)

### Current webhook payload

| 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:

1. Create an event listener by following [these](https://www.pubnub.com/docs/serverless/events-and-actions/configure-e&a#create-event-listener) steps.
2. Add a Webhook action and configure it by following [these](https://www.pubnub.com/docs/serverless/events-and-actions/actions/create-webhook-action) steps.
3. Repeat for each legacy webhook you had configured and want to continue receiving (Presence, Mobile Push Notifications, and Message Persistence).

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