A Web push gateway to proprietary services such as FCM
Upgrade dependencies
Skip logging message on subscription with stale FCM tokens
Shutdown server on SIGINT/SIGTERM


browse  log 



You can also use your local clone with git send-email.


A Web Push gateway to proprietary services such as Firebase Messaging.

      ┌────────────┐             ┌─────────────┐
      │            │  Subscribe  │             │
      │   Android  ├────────────►│ Application │
      │ IRC client │             │   Server    │
      │            │             │             │
      │            │             │             │
      └────────────┘             └──────┬──────┘
             ▲                          │
             │                          │
        Push │                          │Push
notification │                          │notification
             │                          ▼
       ┌─────┴─────┐             ┌─────────────┐
       │           │             │             │
       │ Firebase  │◄────────────┤  pushgarden │
       │ Messaging │ Push        │             │
       │           │ notification│             │
       └───────────┘             └─────────────┘

Web Push is defined in RFC 8030, RFC 8291 and RFC 8292.


Go to your project settings in the Firebase console, select the "Service accounts" tab, and download the private key as a JSON file. Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to a path to this file, then start pushgarden.

The payloads delivered to Firebase are encrypted and need to be decrypted on the client side. The decryption process is very similar to the encryption process.

#Stateless endpoint

For simple use-cases, a stateless push endpoint is available at POST /firebase/<project-id>/push?token=<token>. The <project-id> is visible in the project settings. The per-device <token> can be obtained from the Firebase SDK.

pushgarden will send a Firebase message with the following data:

  • payload: contains the encrypted request body.
  • endpoint: contains the request path.
  • vapid_key: if the request was signed with a VAPID key, contains the public key.

#Stateful endpoint

Alternatively, the stateful endpoint can be used by creating a subscription. This unlocks additional features and improved security:

  • Multiplexing via the endpoint field.
  • A VAPID public key can be specified. Unsigned requests and requests signed with another VAPID key will be rejected.
  • The <token> is not disclosed to push notification senders.
  • The subscription can be deleted as needed.

To create a new subscription, send a request to POST /firebase/<project-id>/subscribe?token=<token>. pushgarden will return a unique push endpoint in a Link response header, for instance:

Link: </firebase/example-560a6/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV>; rel="urn:ietf:params:push"
Location: /firebase/example-560a6/subscription/LBhhw0OohO-Wl4Oi971UG

A POST request to the push endpoint will deliver a new Firebase message (as explained in the previous section). A DELETE request on the subscription endpoint will cancel the subscription.



Copyright (C) 2021 The pushgarden Contributors