Presence Webhooks

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 where the actual channel names may be dynamic and continuously changing, we recommend using Presence Webhooks instead. You'll find Presence Webhooks to be easier to implement and scale.

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

Event Types

There are four UUID level presence events: join, leave, timeout and state-change, and two channel level events are new to you. 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.

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 and not rely on the SDK to generate one for you because it will make it harder for you to associate UUID's 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 action attribute will indicate the type of the event that has occurred: active or inactive.

HTTP POST
Content-Type: multipart/form-data

action=active,
timestamp=<unix-timestamp>,
sub_key=<pubnub-subscribe-key>,
channel=<channel-name>

Note

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);
    }

    if ((event.action === "leave") || (event.action === "timeout")) {
        console.info(event.uuid + " has left or isn't reachable);
        // use pubnub.wherenow() if needed.
    }
    response.status(200).end();
});