Pusher REST API

This document outlines the RESTful interface Pusher exposes to other applications. If you are using a library we are linking to, you won't generally need to consult use this. This is for informational purposes only, and for aiding those who wish to create libraries in other languages.

Pusher `event` resource

Method: POST

URL: http://api.pusherapp.com/apps/[app_id]/channels/[channel_name]/events

Description

Triggers an event on a given channel. This will send a JSON message to all sockets connected to that channel.

Headers

A Content-Type header should be sent identifying the body of the request as application/json.

Parameters

Parameters included in resource:

appid: Application id (from your Pusher application page)
channel_name: Channel name relating to your app (containing alphanumeric characters, ‘-’ and ‘_’)

Query string parameters:

name: Event name (containing alphanumeric characters, ‘-’ and ‘_’)
body_md5: MD5 hash of the request body - used for authentication
socket_id (optional): This will prevent the event from being triggered on a specific WebSocket connection (see excluding event recipients for more info)
Authentication parameters (see below)

The request body should contain the event data as JSON and should be encoded as UTF-8. Upon receipt of data which is not valid UTF-8, the API will return a 400 response code. The pusher javascript library will parse this JSON, and make it available to the bound function:

pusher.bind('event_name', function(parsed_json) {});

Response

The following HTTP status codes are possible

202 ACCEPTED: The event has been received and will be send asynchronously to all sockets.
400 BAD REQUEST: The request body will contain details.
401 UNAUTHORIZED: Authentication failure - the response body will contain details.
404 NOT FOUND: Resource not found - most likely appid does not exist.
500 INTERNAL SERVER ERROR

Authentication parameters

The following query parameters must be included with all requests, and are used to authenticate the request

auth_key: your Pusher application key
auth_timestamp: The number of seconds since January 1, 1970 00:00:00 GMT. The server will only accept requests where the timestamp is within 600s of the current time
auth_signature: Authentication signature, described below
auth_version: Authentication version, currently 1.0

Generating authentication signatures

The signature is a HMAC SHA256 hex digest. This is generated by signing a string made up of the following components concatenated with newline characters \n.

The uppercase request method (e.g. POST)
The request path (e.g. /some/resource)
The query parameters sorted by key, with keys converted to lowercase, then joined as in the query string. Note that the string must not be url escaped (e.g. given the keys auth_key: foo, Name: Something else, you get auth_key=foo&name=Something else)

See below for a concrete example.

Worked example

Assume that we wish to trigger the foo event on the project-3 channel with JSON {"some":"data"} and that our application details are

app_id = '3'
key = '278d425bdf160c739803'
secret = '7ad3773142a6692b25b8'

We first construct the request uri

http://api.pusherapp.com/apps/3/channels/project-3/events

The body of the request should be the event as JSON UTF-8 encoded (with no trailing newline)

{"some":"data"}

We send the following query parameters (which includes the MD5 hash of this body)

name            foo
auth_key        278d425bdf160c739803
auth_timestamp  1272044395
auth_version    1.0
body_md5        7b3d404f5cde4a0b9b8fb4789a0098cb

The signature is generated by signing the following string

POST\n/apps/3/channels/test_channel/events\nauth_key=278d425bdf160c739803&auth_timestamp=1272044395&auth_version=1.0&body_md5=7b3d404f5cde4a0b9b8fb4789a0098cb&name=foo"

This should be signed by generating the HMAC SHA256 hex digest with secret key 7ad3773142a6692b25b8. This will yield the following signature

309fc4be20f04e53e011b00744642d3fe66c2c7c5686f35ed6cd2af6f202e445

The api request then becomes

POST /apps/3/channels/test_channel/events
QUERY auth_key=278d425bdf160c739803&auth_timestamp=1272044395&auth_version=1.0&body_md5=7b3d404f5cde4a0b9b8fb4789a0098cb&name=foo&auth_signature=309fc4be20f04e53e011b00744642d3fe66c2c7c5686f35ed6cd2af6f202e445
BODY {"some":"data"}

Here is the request, with the Content-Type set as application/json and body as {"some":"data"}, and response made with curl

$ curl-H "Content-Type: application/json" -d '{"some":"data"}' "http://api.pusherapp.com/apps/3/channels/test_channel/events?auth_key=278d425bdf160c739803&auth_timestamp=1272044395&auth_version=1.0&body_md5=7b3d404f5cde4a0b9b8fb4789a0098cb&name=foo&auth_signature=309fc4be20f04e53e011b00744642d3fe66c2c7c5686f35ed6cd2af6f202e445"
202 ACCEPTED

If you're having difficulty generating the correct signature in your library please take a look at this ruby gist http://gist.github.com/376898.

Documentation