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.

Event Types

There are four UUID 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 UUID

Presence Events are tracked based on the client's UUID. Hence, for the purpose of Presence Events, it's recommended that UUID is set by you. You shouldn't rely on the SDK to generate UUID 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 UUID. To learn more, visit Managing Identity.

Presence throttling

Presence Webhooks still follows the Announce-Max message throttling behavior of PubNub Presence, so please take this into consideration while building your Webhooks.

Presence Webhooks Payloads

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

UUID Events: Join, Leave, Timeout and State-Change Events

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

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

Channel Events: Active and Inactive

Payload for the Active and Inactive events will follow the below mentioned format. The status attribute will indicate the type of the event that has occurred: active or inactive.

HTTP POST
Content-Type: multipart/form-data

status=active,
timestamp=<unix-timestamp>,
sub_key=<pubnub-subscribe-key>,
channel=<channel-name>
Webhooks format

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

Presence Webhook Response Status

It's important that your REST endpoint responds 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 UUID Events

Sample API implementation using Node.js.

app.post("/chatterbox/api/v1/wh/presence", (request, response) => {
var event = request.body;
console.info('entering presence webhook for uuid/user: ' + event.uuid);

if ((!event) || (!event.action) || (!event.uuid)) {
console.info("could not process event: " + JSON.stringify(event));
response.status(200).end();
return;
}
if (event.action === "join") {
console.info(event.uuid + " has join " + event.channel);
}

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