Webhooks
========

PushItGood can call a webhook to tell your application about subscription and notifcation events.


The webhook endpoint
--------------------

If you provide a webhook endpoint, pushitgood will ping it on each of the
following events:

====================================================================== ================ ================
Event                                                                  event_type       State
====================================================================== ================ ================
User subscribes                                                        ``subscription`` ``subscribed``

User unsubscribes                                                      ``subscription`` ``unsubscribed``

Push sent to a user                                                    ``push``         ``sent``

Push rejected by the upstream webpush service due to user unsubscribe  ``push``         ``gone``

Push rejected by the upstream webpush service, any other reason        ``push``         ``failed``

Push acknowledged by the browser                                       ``push``         ``received``

Push timed out (no browser acknowledgement within timeout period)      ``push``         ``timeout``
==================================================================     ================ ================

The endpoint must accept a POST request containing a Javascript Web Token.
A sample Python implementation looks like this:

.. code:: python

    def webhook(request):
        data = jwt.decode(request.get_body(), key=APIKEY)

        # Either 'subscription' or 'notification'
        event_type = data["event_type"]

        # The user id as supplied by your user-details endpoint
        uid = data["uid"]

        # The user's subscription id
        sid = data["sid"]

        # If event_type is 'push', contains the notification's unique id
        # This will match the id returned by the api endpoint when you sent the notification
        nid = data["nid"]

        # The push id
        pid = data["pid"]

        # If event_type is 'subscription', this will be one of subscribed, unsubscribed
        #
        # If event_type is 'notification', this will be one of:
        # - sent: the notification has been accepted by the vendor supplied endpoint
        # - failed: the notification could not be sent
        # - received:the notification was received by the service worker on a user's device
        # - timeout: the notification was not received by the user's device after the specified delay
        state = data["state"]

        print(
            f"Push with id {pid} to user {uid} now has state {state}"
        )

        # Return an empty response
        return Response()

Note that the browser allows users to stop notifications by disabling the
notification permission – and in some cases encourages the user to do this if
the site sends repeated notifications.

When this happens, the browser does not inform our service, and so the
unsubscribe web hook is **not** called. The next time you send a notification
you will receive a timeout webhook for this device.


How to specifiy your webhook location
-------------------------------------

The webhook URL must be specified when subscribing a user, using the :ref:`user details endpoint <UserDetails>`.