Presence Webhooks

PubNub can invoke a REST endpoint on your server when presence events occur.

The standard way for PubNub developers to consume Presence data is via the client SDK's Presence APIs, such as subscribe(). However, if you have a large number of channels in your implementation, or if your channel names are dynamic and continuously changing, we recommend using Presence webhooks instead.

Once the callback URLs are provided for the presence events, PubNub servers will HTTP POST the same data to your callback URLs, in addition to publishing Presence events on the -pnpres channels. All Presence events, across all channels for a given keyset, will POST to this endpoint.

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

Event Types

There are four User ID level presence events: joinleavetimeout and state-change, and two channel level events: active and inactive. When a channel occupancy goes from 0 to 1 (or more), it's active, and when it goes from 1 to 0, it's inactive.

Setup and Configuration

Each event type has it's own Webhook for which you can configure a REST POST endpoint to handle the event. You can configure them in your PubNub Key's configuration on the Admin Portal.

Presence Callback Settings no PubNub admin portal

Configure your User ID

Presence Events are tracked based on the client's User ID. Hence, for Presence Events, it's recommended that User ID is set by you. You shouldn't rely on the SDK to generate a User ID for you because it will make it harder for you to associate its Presence activity with a known user (or userID). There are no strict requirements on the format of User ID. To learn more, visit Managing Identity.

Presence throttling

Presence Webhooks still follows the Announce-Max message throttling behavior of Presence, so consider this while building your Webhooks.

Presence Webhooks Payloads

The following are the Webhook payloads, organized by Presence Event Type.

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

User ID Events: Join, Leave, Timeout and State-Change Events

Payload for the Join, Leave, Timeout, and State-Change events follow the same format. The action attribute will indicate the type of the event that has occurred: join, leave, timeout, or state-change.

Content-Type: application/json
"action" : "join",
"sub_key" : <pubnub-subscribe-key>,
"channel" : <channel>,
"uuid" : <userID>,
"timestamp" : <unix-timestamp>,
"occupancy" : <#-users-in-channel>,
"data" : <full-state-data-associated-with-userID>

Channel Events: Active and Inactive

Payload for the Active and Inactive events follow the same format. The status attribute indicates the type of the event that has occurred: active or inactive.

Content-Type: multipart/form-data

Webhooks format

The Active and Inactive webhooks are multipart/form-data and not JSON.

Presence Webhook Response Status

Your REST endpoint must respond with a status code 200 immediately upon receiving the Presence webhook. Failure to send the response back will result in PubNub sending duplicate events. PubNub will wait up to 5 seconds for the response before trying again. After a third retry (four total attempts), PubNub will no longer attempt to send that particular event to your server.

Sample Implementation for User ID Events

Sample API implementation using Node.js."/chatterbox/api/v1/wh/presence", (request, response) => {
var event = request.body;'entering presence webhook for uuid/user: ' + event.uuid);

if ((!event) || (!event.action) || (!event.uuid)) {"could not process event: " + JSON.stringify(event));
if (event.action === "join") { + " has join " +;

if (event.action === "state-change" && event.state) {"state changed for " + event.uuid + " new state " + event.state);
show all 23 lines
Last updated on