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: join, leave, timeout 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.
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.
HTTP POST
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.
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
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.
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);