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