Forward push errors and device removals to your endpoint

Send Mobile Push Notifications errors and device removals to your own endpoint with Events & Actions, PubNub's no-code feature that forwards keyset events to external systems. This setup replaces the legacy Push Webhooks keyset setting. Create one Webhook action, then create an event listener for Push error and one for Device removed, and pair both with the action.

Before you start, confirm that your plan includes the number of listeners you need. Refer to Availability by plan. Each active listener adds to your billed event count, as described in Billing. You also need an HTTPS endpoint that can receive the events.

Create the Webhook action

1. Open the Admin Portal, select Events & Actions, and select the app and keyset that sends your push notifications.
2. Click + Add Action and select Webhook.
3. Under Configuration, enter the HTTPS URL of your endpoint.
4. Turn on Is Enveloped. Enveloped Events & Actions payloads use schema version 1.0, 2.0, or 2.1; 2.1 is the default when enveloping is enabled. Actions without an envelope use the no-envelope format. The examples on this page use version 2.1.
5. Click Save changes.

For custom headers, batching, and retries, refer to Create a Webhook action. With batching on, one request carries several events, and the examples on this page show one event.

Create a listener for each push event

1. In Events & Actions, click + Add Event Listener and choose the Mobile Push event source.
2. Choose the Devices event producer and the Push error event type.
3. Select No filter to receive every push error on the keyset.
4. Under Add Action, pick the Webhook action you created.
5. Click Save Changes.
6. Repeat these steps for the Device removed event type.

For filters and the other listener options, refer to Configure Events & Actions.

Confirm events arrive

Trigger a push error or a device removal on the keyset, then check that your endpoint receives a request. In Events & Actions, the Event Listeners and Actions lists show how many times each listener and action has run. If the counts don't increase, check that the listener uses the right event type and is paired with the action.

Read the events

With the envelope on, event.payload.dataSchema names the event type, and event.payload.data is an array of records. Loop over every record in data.

Event type	dataSchema
Push error	pubnub.com/schemas/events/push.message.sending.failed?v=1.0.0
Device removed	pubnub.com/schemas/events/push.device.removed?v=1.0.0

In a Push error record, payload holds the error message, and channel and platform show where the push was sent:

1{
2    "event": {
3        "id": "e2d4bb46-12a0-4fde-83a4-46c8cd4c7c14",
4        "payload": {
5            "dataSchema": "pubnub.com/schemas/events/push.message.sending.failed?v=1.0.0",
6            "data": [
7                {
8                    "id": "52301823-51f5-47d7-962c-16ac657f752a",
9                    "channel": "pn-in.dFVj.lpxY",
10                    "devices": "",
11                    "platform": "apns",
12                    "timestamp": "2025-06-18T04:16:59.353913Z",
13                    "subKey": "sub-c-a5015666-3dd3-42df-8074-d37d647e8fe9",
14                    "state": "error",
15                    "payload": "APNS payload error: APNS notification exceeds max size"
16                }
17            ]
18        }
19    },
20    "metadata": {
21        "provenance": {
22            "listenerId": "1b526cbb-4e4c-4f19-8f77-ea862d94115c",
23            "action": {
24                "id": "0159494b-18a3-4c0a-95ab-b12fb0ba73cf",
25                "instanceId": "85b12038-8a23-4152-9a62-ccdb184e9b01",
26                "invocation": {
27                    "id": "90c56456-7f1e-4036-8200-af650ea21d54",
28                    "attempt": 0
29                }
30            }
31        }
32    },
33    "schema": "https://www.pubnub.com/schemas/edp.ena.event?schema-instance+json?v=2.1"
34}

show all 34 lines

In a Device removed record, device holds the device token and platform its push service:

1{
2    "event": {
3        "id": "e2d4bb46-12a0-4fde-83a4-46c8cd4c7c14",
4        "payload": {
5            "dataSchema": "pubnub.com/schemas/events/push.device.removed?v=1.0.0",
6            "data": [
7                {
8                    "id": "12345",
9                    "action": "remove",
10                    "device": "device_token_abc",
11                    "platform": "ios",
12                    "timestamp": "2024-06-10T12:34:56Z",
13                    "subKey": "sub-c-xyz",
14                    "oldDevice": "old_device_token_def"
15                }
16            ]
17        }
18    },
19    "metadata": {
20        "provenance": {
21            "listenerId": "1b526cbb-4e4c-4f19-8f77-ea862d94115c",
22            "action": {
23                "id": "0159494b-18a3-4c0a-95ab-b12fb0ba73cf",
24                "instanceId": "85b12038-8a23-4152-9a62-ccdb184e9b01",
25                "invocation": {
26                    "id": "90c56456-7f1e-4036-8200-af650ea21d54",
27                    "attempt": 0
28                }
29            }
30        }
31    },
32    "schema": "https://www.pubnub.com/schemas/edp.ena.event?schema-instance+json?v=2.1"
33}

show all 33 lines

metadata.provenance.listenerId identifies the listener that matched the event. For the other envelope versions of both events, refer to Device removed and Push error in the payloads reference.

If you configured Push Webhooks on the Admin Portal Keysets page before Events & Actions, your code may still parse the legacy payload. Refer to Migrate from legacy webhooks to Events & Actions.

Related tasks

• Create a Webhook action. Add custom headers, batching, and retries to the action.
• Configure Events & Actions. Filter which events a listener matches.
• Events & Actions payloads. Look up every envelope version of every event type.
• Debug push notification messages. Inspect one push through the -pndebug companion channel.
• Check push device registration. Confirm which channels a device token is currently registered on.
• Check the FCM payload. Confirm that an FCM payload uses the message type your app expects.
• Mobile push notifications. Understand how PubNub routes a published message to APNs and FCM.