Webhooks

If you specify a webhookUrl when publishing a notification we will send requests to that URL to keep you up to date on how your publish is doing (including any errors that may occur).

All webhooks will be sent as POST requests with a JSON body.

Set Up a Webhook URL

The first step to using webhooks is to set up a URL route on a webserver capable of receiving POST requests and parsing JSON request bodies.

Securing Webhooks

When you receive an incoming webhook you may want to check that the incoming request actually came from Pusher. You can do this by adding secret basic auth credentials to your webhook URL: https://username:password@yourwebsite.com/webhook-path

You can then check that incoming webhooks are really coming from Pusher by parsing your credentials out of the Authorizationheader of the incoming request.

Basic Auth Authorization headers look something like this:

1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
where the encoded part can be created by base64 encoding your secret username and password separated by a colon (in this example username:password)

You can find more information on how to do this here.

Make sure your webhook URL is using https. Otherwise you could be leaking sensitive data.

Publish a Push Notification

Using one of our server SDKs (or raw HTTP) send a request to the publish API making sure to set the webhookUrl parameter to the URL you just created.

Example Publish Body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "interests": [
    "my_interest",
  ],
  "webhookUrl": "http://mysite.com/push-webhook",
  "apns": {
    "aps": {
      "alert": {
        "title": "New Message",
        "body": "Alex Smith just sent you a new message"
      }
    }
  }
}

Parse the Webhook Body

Some post requests should now have been sent to your webhook URL. To find out what to expect in the request body take a look at the webhook reference documentation.

Did you find this document useful?

We are always striving to create the most accurate and informative docs as possible. If there is something especially wrong (or right) here then please let us know.