Pushover Subscriptions are an easy way to collect Pushover user keys for an application to broadcast notifications to a bunch of users without any administration.
successparameter you attached to the URL in step 2; you should store the
pushover_user_keyparameter you receive and associate it with the current user
userparameter, send your group's key (if using group-based subscriptions) or your new subscribed user's key (which we sent as
pushover_user_keyin step 4)
To get started with Pushover Subscriptions, view your application and click "Edit Subscription Settings". Fill out the required fields and a subscription key and URL will be created based on your application's name.
For applications that broadcast the same notifications to all subscribed users (such as news sites or blog updates), we recommend opting for a Group-based subscription. With this type of subscription, no further action is needed on your part to manage users. You can then direct users to the subscription URL that we provide and everything will be handled on our end.
For private applications or those sending individual notifications to users (such as a forum sending private messages to users, or a network monitoring system), you will need to choose a URL-based subscription. With this type of subscription, you must store the user's key in your database and associate it with the current user. See below for more information.
For group-based subscriptions, users can initiate the subscription process just by navigating to your subscription URL (found in your app's settings). Users can find your subscription by clicking on a link that you send them in an e-mail, or by scanning a QR code, or any other mechanism. Once the user visits your subscription URL and confirms the request, they will be automatically added to your group and the process is complete.
For web-based subscriptions, the process is a bit more complicated because we need to direct the user back to your website after subscribing and pass along their new Pushover user key. The details of this process can be found below.
For both subscription types, we have some buttons you can use to initiate a subscription process for your user.
For applications sending private notifications, the web-based
subscription process will typically start on your own website. Your
website will need to display a link or button
somewhere that users can click on to initiate the subscription process.
When the user clicks on the link/button, they should be directed to your
application's subscription URL with the
pointing back to your website.
After subscribing, the user will be redirected back to the URL you
specified as the
success parameter, and we will include a
pushover_user_key parameter with the user's new key.
If the user decides not to subscribe, they will be redirected back to a
URL you specify as the
failure parameter, or your
subscription's base URL if not supplied. If an already-subscribed user
chooses to unsubscribe, they will be redirected back to your
success URL with a blank
parameter and the
pushover_unsubscribed parameter set to
To illustrate how this process works, we'll work with a fictitious
website called Forum
that operates at
users are logged into the Forum, they can view their user settings page
https://forum.example.com/settings and enable
Pushover settings by clicking on a button. Once users are subscribed, we
want them redirected back to
https://forum.example.com/settings/enable_pushover where we
will read the new Pushover user key, save it, and display a confirmation
message to the user.
To start, we'll create a Pushover application
and get an API token. Then, create a subscription by clicking on "Edit
Subscription Settings" and choose a web-based subscription type with a
base URL of
https://forum.example.com/. After creating the
subscription, a subscription URL will be shown:
Since we want users redirected back to
subscribing, that URL must be URL-encoded and appended as the
success parameter to the subscription URL above. If the
user decides not to subscribe, we want to redirect them back to
https://forum.example.com/settings, so we will include that
To improve security, before redirecting the user
to the Pushover subscription page, we're going to store a random piece of
data in the user's session (
m5St1Fe67ly5d6). We'll then
append that to our
success URL and later verify that we got
it back. Our
success URL now looks like
which we URL encode and append to our subscribe URL along with our
Note that because the subscription was initially created with a base URL
failure URL parameters that you supply must start
with that. If the
success URL is missing or contains a URL
that does not begin with the subscription's base URL, we will display an
error and abort the subscription process as a security measure to prevent
users from being redirected back to a rogue website. If the
failure URL is not supplied, we will redirect the user back
to the base URL upon denying a subscription request.
Continuing in our example, the user is now on the Pushover website at
your application's subscription URL. The user confirms the subscription
and they are redirected back to your
success URL, including
the user's new Pushover key as a parameter:
Once the user arrives back at the
URL on your website, your application can verify that the random token
received in the URL is what was stored in the user's session (see security below for more information) and then look
pushover_user_key parameter and associate it to the
current user's account.
pushover_user_key parameter is blank, the user was
previously subscribed and has chosen to unsubscribe (a
pushover_unsubscribed parameter set to
also be included). You should clear any saved Pushover user key for this
We've provided some example HTML/CSS for use on your website when directing the user to your subscription URL to subscribe or manage their subscription if already subscribed. Both should use the URL of your subscription (passing any parameters as detailed above).
This would create a styled link that looks like a button:
The example shown above uses a random token mechanism to avoid a
potential security problem: because we are redirecting users to a
success URL, it is possible for an attacker to
force a user to access that URL with a custom
pushover_user_key that the attacker controls. Without any
validation, your application would just store that Pushover user key on
the user's account and begin sending private notifications meant for the
user to the attacker.
To avoid this security problem, you could store a random piece of data
in the user's session on your website before sending them to the
subscription URL. This piece of data would be something that only that
particular user would be able to access and an attacker would not. Then,
by appending it to your
success URL in a way that your
application can later check for, we pass it through upon redirection and
your application can verify that the random token we passed through
matches what is in the user's session. If the verification failed, your
application would not store the received
(and probably notify someone about a security breach attempt).
Because this process of generating random data, adding it to the user's session, and verifying it from the URL is highly dependent upon how your website is built, we leave this up to you to implement. As an example using PHP, your Pushover button could call the following code to create a random token, add it to the user's session, and then redirect the user to your subscription URL:
<?php $_SESSION["pushover_rand"] = bin2hex(openssl_random_pseudo_bytes(20)); header("Location: https://pushover.net/subscribe/Forum-f504h08fhlasdfj" . "?success=" . urlencode("https://forum.example.com/settings/enable_pushover?rand=" . $_SESSION["pushover_rand"]) . "&failure=" . urlencode("https://forum.example.com/settings")); ?>
Then the code at
/settings/enable_pushover would verify that
the supplied random token in the URL matches the session token before
<?php if (empty($_SESSION["pushover_rand"])) die("no random token in session"); if (empty($_REQUEST["rand"]) || $_REQUEST["rand"] !== $_SESSION["pushover_rand"]) die("no random token passed through pushover, possible security problem"); // verification passed, it's now ok to save $_REQUEST["pushover_user_key"] ... ?>
Applications that formerly collected Pushover user keys are encouraged to
migrate to subscription keys. This API call takes an application
subscription code, and a
user key and creates a subscription for the user. Upon
receiving a successful API response, you can discard the user's key and
save the received
subscribed_user_key in place of it.
To migrate your users, send one POST request for each user (HTTP keep-alive supported to send multiple requests over the same connection) to:
Include the following parameters:
token(required) - your application's API token
subscription(required) - your subscription's code
user(required) - the user's Pushover user key
device_name(optional) - a user's device name that the subscription should be limited to
sound(optional) - a user's preferred default sound
Upon success, you will receive a
status code of
1 and a
subscribed_user_key parameter to save
in place of the user's original