Webhook Reference

Webhooks will are sent as POST requests with a JSON body. The request body contains a generic wrapper around the following event-specific payloads:

Webhooks for Pusher Beams are currently in beta. Let us know if we can make any improvements at betterbeams@pusher.com

v1.PublishToUsersAttempt

Contains a summary of what happened during a publish to one or more Authenticated Users.

Payload Schema

Key NameTypeDescription
instance_idstringID of the Pusher Beams instance that made this publish request.
publish_idstringUnique ID of the completed publish request.
users_delivered_to_gatewayArray<string>List of IDs of users who have had a notification accepted by the gateway (FCM / APNs) for at least one of their devices.
users_no_devicesArray<string>List of IDs of users that do not have any devices registered with Pusher Beams.
users_gateway_failedArray<string>List of IDs of users that could not be delivered to due to transient issues with the gateway (FCM / APNs).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "payload": {
    "instance_id": "9c83c1b2-77ac-49c5-94c2-bfc96f9bec49",
    "publish_id": "pubid-1df0b272-910b-43f7-9271-7345036aa739",
    "users_delivered_to_gateway": [
      "user-001",
      "user-002",
      "user-003",
      "user-004"
    ],
    "users_no_devices": [
      "user-005"
    ],
    "users_gateway_failed": []
  },
  "metadata": {
    "created_at": "2019-03-11T10:42:16+0000",
    "event_type": "v1.PublishToUsersAttempt",
    "event_id": "e1b9d31a-480e-43dc-ae97-93ed96576372",
    "product": "beams"
  },
  "custom_data": {}
}

v1.UserNotificationAcknowledgement

Sent when a notification is acknowledged as delivered by a user's device.

This webhook requires that the target device be running at least one of the following SDK versions:

  • iOS - 1.3.0
  • Android - 1.4.0

Payload Schema

Key NameTypeDescription
instance_idstringID of the Pusher Beams instance that triggered this event.
publish_idstringUnique ID of the publish request that triggered this event.
user_idstringID of the user that received this notification.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "payload": {
    "instance_id": "9c83c1b2-77ac-49c5-94c2-bfc96f9bec49",
    "publish_id": "pubid-1df0b272-910b-43f7-9271-7345036aa739",
    "user_id": "user-001"
  },
  "metadata": {
    "created_at": "2019-03-11T10:42:16+0000",
    "event_type": "v1.UserNotificationAcknowledgement",
    "event_id": "e1b9d31a-480e-43dc-ae97-93ed96576372",
    "product": "beams"
  },
  "custom_data": {}
}

v1.UserNotificationOpen

Sent when a notification is opened by a user on one of their devices.

This webhook requires that the target device be running at least one of the following SDK versions:

  • iOS - 1.3.0
  • Android - 1.4.0

Payload Schema

Key NameTypeDescription
instance_idstringID of the Pusher Beams instance that triggered this event.
publish_idstringUnique ID of the publish request that triggered this event.
user_idstringID of the user that opened this notification.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "payload": {
    "instance_id": "9c83c1b2-77ac-49c5-94c2-bfc96f9bec49",
    "publish_id": "pubid-1df0b272-910b-43f7-9271-7345036aa739",
    "user_id": "user-001"
  },
  "metadata": {
    "created_at": "2019-03-11T10:42:16+0000",
    "event_type": "v1.UserNotificationOpen",
    "event_id": "e1b9d31a-480e-43dc-ae97-93ed96576372",
    "product": "beams"
  },
  "custom_data": {}
}

Publish Webhooks (deprecated)

All webhooks are POST requests with JSON bodies sent to the webhookUrl specified when publishing.

Publish Started Hook

Indicates we have started publishing to the devices subscribed to the specified interests.

Payload Schema

Key NameTypeDescription
publish_idstringUnique ID of the publish request that triggered this event.
statusstringString constant which indicates the webhook type. Equal to STARTED
request_bodyobjectThe body of the request sent to the Publish API when publishing this notification

Example

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "publishId": "pubid-9e5f186a-93d9-4b79-af37-2a946d73e2b5",
  "status": "STARTED",
  "requestBody": {
    "interests": [
      "my_interest",
    ],
    "webhookUrl": "http://mysite.com/push-webhook",
    "fcm": {
      "notification": {
        "title": "New Message",
        "body": "Alex Smith just sent you a new message"
      }
    },
    "apns": {
      "aps": {
        "alert": {
          "title": "New Message",
          "body": "Alex Smith just sent you a new message"
        }
      }
    }
  }
}

Publish Finished Hook

Indicates we have finished publishing the push notification to devices subscribed to the specified interests.

Payload Schema

Key NameTypeDescription
publish_idstringUnique ID of the publish request that triggered this event.
statusstringString constant which indicates the webhook type. Equal to FINISHED
request_bodyobjectThe body of the request sent to the Publish API when publishing this notification
resultsobjectThe name of the platform (apns/fcm) to the result object for that platform

Result Object Schema

Key NameTypeDescription
failedboolean, default=falseIf this field istrue this means that the publishing process for the specified platform has failed completely and no other statistics can be given.
numSuccessfulPublishesnumberThe number of devices successfully published to
numFailedPublishesnumberThe number of devices where publishing failed

Example

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "publishId": "pubid-9e5f186a-93d9-4b79-af37-2a946d73e2b5",
  "status": "FINISHED",
  "requestBody": {
    "interests": [
      "my_interest",
    ],
    "webhookUrl": "http://mysite.com/push-webhook",
    "fcm": {
      "notification": {
        "title": "New Message",
        "body": "Alex Smith just sent you a new message"
      }
    },
    "apns": {
      "aps": {
        "alert": {
          "title": "New Message",
          "body": "Alex Smith just sent you a new message"
        }
      }
    }
  },
  "results": {
    "apns": {
      "numSuccessfulPublishes": 486546,
      "numFailedPublishes": 5
    },
    "fcm": {
      "numSuccessfulPublishes": 98423
    }
  }
}