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:

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

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 user details endpoint.