Receiving Client Events via Webhooks

It’s always a good day in the Pusher office when we can announce a new feature for you all to use. This time around we’re happy to unveil our new client_event Webhook, allowing you to be notified on your server as soon as Client Events are sent within a Private or Presence Channel on your application.

The client_event Webhook is a simple but powerful feature and it requires little effort on your part to start using it, just a REST endpoint to have the Client Events sent to.

Why do I need the Client Event Webhook?

If you’ve ever wanted to receive Client Events on your server then this is going to help you out immensely. You no longer have to use a client library on the server to receive messages, instead you can use the Webhook to receive them in a format that makes sense and is easy to manage on your server. Bear in mind that this only applies to messages sent as Client Events.

How is the Webhook data structured?

The data payload within the client_event Webhook is a JSON object, structured like this:

ruby
1{
2  "time_ms": timestamp in milliseconds since epoch,
3  "events": [
4    {
5      "name": "client_event",
6      "channel": "name of the channel the event was published on",
7      "event": "name of the event",
8      "data": "data associated with the event",
9      "socket_id": "socket_id of the sending socket",
10      "user_id": "user_id associated with the sending socket" # Only for presence channels
11    }
12  ]
13}
Copy

Here is an example of a real Webhook response from a Private Channel:

ruby
1{
2  "time_ms": 1396258618139,
3  "events": [
4    {
5      "name": "client_event",
6      "channel": "private-test_channel",
7      "event": "client-my_event",
8      "data": "{"data":1234}",
9      "socket_id": "34718.5367461"
10    }
11  ]
12}
Copy

If you’re still unsure, our documentation on Webhooks explains the payload data format and processing in a little more detail.

How do I use it?

Pusher will send a client_event event whenever a client event is sent on any private or presence channel, but first you need to set things up.

Step 1: Enable the Client Event Webhook

The first thing you need to do is go into your application dashboard and create a new Webhook for Client Events. Set the WebHook URL to the endpoint on your server that will be receiving the Webhooks.

Step 2: Set up the endpoint on your server

This Node.js example will get you up and running with consuming the new client_event Webhook. Though the following basic process is the same for all platforms:

• Set up a REST endpoint for the Webhook (in this case /client_event)
• Deconstruct the Webhook payload and process it how you wish

Note: This assumes you are using Express 3. If you’re using Express 4 then you’ll need to use the updated API

javascript
1// Require Express (HTTP server)
2// http://expressjs.com
3var express = require("express");
4var app = express();
5var server = require("http").createServer(app);
6
7// Configure Express server
8app.configure(function(){
9  app.use(express.bodyParser());
10  app.use(express.errorHandler({
11    dumpExceptions: true,
12    showStack: true
13  }));
14});
15
16// Webhook endpoint
17app.post("/client_event", function(req, res) {
18  var timestamp = req.body.time_ms;
19  var events = req.body.events;
20
21  console.log(events);
22
23  // Respond with a success code
24  res.send(200);
25});
26
27// Set up HTTP server to listen on system port, or port 5000
28server.listen(process.env.PORT || 5000);
Copy

Testing the Webhook using RequestBin

If you’re having trouble getting the Webhook to work, it’s a good idea to test things using RequestBin. To do this you’ll want to set up a new RequestBin and use the given URL as the endpoint for the Webhook on your Pusher dashboard. Anything sent to that URL will show up on RequestBin and will quickly show you whether things are set up correctly.

More soon

This is just one of many new features and improvements that we’re working on. We can’t wait to show you the rest and we’ll keep you updated as we get closer to releasing them.

In the meantime, let us know what you use this new Webhook for!