---
source_url: https://www.pubnub.com/docs/integrations/mobile-push-notifications/set-up-push-webhooks
title: Forward push errors and device removals to your endpoint
updated_at: 2026-09-30T07:20:08.000Z
---

# Forward push errors and device removals to your endpoint

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

Send Mobile Push Notifications errors and device removals to your own endpoint with [Events & Actions](https://www.pubnub.com/docs/integrations/event-forwarding/overview.md), 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](https://www.pubnub.com/docs/integrations/event-forwarding/overview.md#availability-by-plan). Each active listener adds to your billed event count, as described in [Billing](https://www.pubnub.com/docs/integrations/event-forwarding/overview.md#billing). You also need an HTTPS endpoint that can receive the events.

## Create the Webhook action

1. Open the [Admin Portal](https://admin.pubnub.com/), 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](https://www.pubnub.com/docs/integrations/event-forwarding/create-webhook-action.md). 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](https://www.pubnub.com/docs/integrations/event-forwarding/configure.md).

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

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

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

```json
{
    "event": {
        "id": "e2d4bb46-12a0-4fde-83a4-46c8cd4c7c14",
        "payload": {
            "dataSchema": "pubnub.com/schemas/events/push.device.removed?v=1.0.0",
            "data": [
                {
                    "id": "12345",
                    "action": "remove",
                    "device": "device_token_abc",
                    "platform": "ios",
                    "timestamp": "2024-06-10T12:34:56Z",
                    "subKey": "sub-c-xyz",
                    "oldDevice": "old_device_token_def"
                }
            ]
        }
    },
    "metadata": {
        "provenance": {
            "listenerId": "1b526cbb-4e4c-4f19-8f77-ea862d94115c",
            "action": {
                "id": "0159494b-18a3-4c0a-95ab-b12fb0ba73cf",
                "instanceId": "85b12038-8a23-4152-9a62-ccdb184e9b01",
                "invocation": {
                    "id": "90c56456-7f1e-4036-8200-af650ea21d54",
                    "attempt": 0
                }
            }
        }
    },
    "schema": "https://www.pubnub.com/schemas/edp.ena.event?schema-instance+json?v=2.1"
}
```

`metadata.provenance.listenerId` identifies the listener that matched the event. For the other envelope versions of both events, refer to [Device removed](https://www.pubnub.com/docs/integrations/event-forwarding/payloads.md#device-removed) and [Push error](https://www.pubnub.com/docs/integrations/event-forwarding/payloads.md#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](https://www.pubnub.com/docs/migration-guides/legacy-webhooks.md#update-mobile-push-notifications-parsing).

## Related tasks

* [Create a Webhook action](https://www.pubnub.com/docs/integrations/event-forwarding/create-webhook-action.md). Add custom headers, batching, and retries to the action.
* [Configure Events & Actions](https://www.pubnub.com/docs/integrations/event-forwarding/configure.md). Filter which events a listener matches.
* [Events & Actions payloads](https://www.pubnub.com/docs/integrations/event-forwarding/payloads.md). Look up every envelope version of every event type.
* [Debug push notification messages](https://www.pubnub.com/docs/integrations/mobile-push-notifications/debug-push-notification-messages.md). Inspect one push through the `-pndebug` companion channel.
* [Check push device registration](https://www.pubnub.com/docs/integrations/mobile-push-notifications/check-push-device-registration.md). Confirm which channels a device token is currently registered on.
* [Check the FCM payload](https://www.pubnub.com/docs/integrations/mobile-push-notifications/check-fcm-payload.md). Confirm that an FCM payload uses the message type your app expects.
* [Mobile push notifications](https://www.pubnub.com/docs/integrations/mobile-push-notifications/overview.md). Understand how PubNub routes a published message to APNs and FCM.

Last updated at: 2026-09-30T07:20:08.000Z