WebHooks
WebHooks allow your server to be notified about events occurring within Pusher.
You can activate WebHooks in your account dashboard on a per app basis. For general information on WebHooks, see the webhooks.org Wiki.
WebHook Format
A WebHook is sent as a HTTP POST request to the url which you specify.
The POST request payload contains a JSON document, and follows the following format:
{
"time_ms": 1327078148132
"events": [
{ "name": "event_name", "some": "data" }
]
}
- The
time_mskey provides the unix timestamp in milliseconds when the WebHook was created. This allows you to detect delayed WebHooks if necessary. - The
eventskey contains one or more events. Each event contains aname, and event specific data.
Your server should respond to the POST request with a 2XX status code to indicate that the WebHook has been successfully received. If a non 2XX status code is returned, Pusher will retry sending the WebHook, with exponential backoff, for 5 minutes. This ensures that temporary failure should not affect your ability to receive all WebHooks.
Security
Encryption
You may use a HTTP or a HTTPS url for WebHooks. In most cases HTTP is sufficient, but HTTPS can be useful if your data is sensitive or if you wish to protect against replay attacks for example.
Authentication
Since anyone could in principle send WebHooks to your application, it's important to verify that these WebHooks originated from Pusher. Valid WebHooks will therefore contain these headers which contain a HMAC signature of the WebHook payload:
HTTP_X_PUSHER_KEY: A Pusher app may contain multiple tokens. The oldest active token will be used, as identified by this key.HTTP_X_PUSHER_SIGNATURE: A HMAC SHA256 hex digest formed by signing the POST payload with the token's secret.
Events
Channel existence events
By subscribing to channel existence events you can, for example, only publish events to a channel when somebody is actually subscribed to that channel.
channel_occupied
When you enable channel existence events, Pusher will send a channel_occupied event whenever any channel becomes occupied (i.e. there is at least one subscriber).
The event data for this event is as follows:
{ "name": "channel_occupied", "channel": "test_channel" }
channel_vacated
When you enable channel existence events, Pusher will send a channel_vacated event whenever any channel becomes vacated (i.e. there are no subscribers).
The event data for this event is as follows:
{ "name": "channel_vacated", "channel": "test_channel" }
Examples
class PusherController < ApplicationController
def webhook
webhook = Pusher::WebHook.new(request)
if webhook.valid?
webhook.events.each do |event|
case event["name"]
when 'channel_occupied'
puts "Channel occupied: #{event["channel"]}"
when 'channel_vacated'
puts "Channel vacated: #{event["channel"]}"
end
end
render text: 'ok'
else
render text: 'invalid', status: 401
end
end
end
# The WebHook object should be initialised with a Rack::Request object, therefore it can be used with any Rack server. Here's a Sinatra example:
post '/webhooks' do
webhook = Pusher::WebHook.new(request)
if webhook.valid?
webhook.events.each do |event|
case event["name"]
when 'channel_occupied'
puts "Channel occupied: #{event["channel"]}"
when 'channel_vacated'
puts "Channel vacated: #{event["channel"]}"
end
end
else
status 401
end
return
end
<?php
// environmental variable must be set
$app_secret = getenv('PUSHER_APP_SECRET');
$app_key = $_SERVER ['HTTP_X_PUSHER_KEY'];
$webhook_signature = $_SERVER ['HTTP_X_PUSHER_SIGNATURE'];
$body = file_get_contents('php://input');
$expected_signature = hash_hmac( 'sha256', $body, $app_secret, false );
if($webhook_signature == $expected_signature) {
$payload = json_decode($body);
foreach($payload['events'] as &$event) {
// do something with the event
}
header("Status: 200 OK");
}
else {
header("Status: 401 Not authenticated");
}
?>