Web Push Elixir

Simple web push library for Elixir

Prerequisities

• Elixir 1.18
• OTP 26 / 27 / 28

Installation

1. Add web_push_elixir to your list of dependencies in mix.exs:

def deps do
  [
    {:web_push_elixir, "~> 0.8.0"}
  ]
end

2. Run mix command to generate your Vapid public and private keys:

mix generate.vapid.keys

3. Set config for your generated keys:

config :web_push_elixir,
  vapid_public_key: "someVapidPublicKey",
  vapid_private_key: "someVapidPrivateKey",
  vapid_subject: "mailto:[email protected]"

Usage

WebPushElixir provides a simple send_notification/2 that takes 2 arguments:

• subscription: the subscription information received from the client - example demo
• message: the message string.

subscription = '{"endpoint":"https://some-push-service","keys":{"p256dh":"BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA_0QTpQtUbVlUls0VJXg7A8u-Ts1XbjhazAkj7I99e8QcYP7DkM=","auth":"tBHItJI5svbpez7KI4CCXg=="}}'
message = "Some message"

WebPushElixir.send_notification(subscription, message)

For more information on how to subscribe a client, permission UX and more - take a look at https://web.dev/notifications/

Error Handling

WebPushElixir returns error types to help you handle failures:

case WebPushElixir.send_notification(subscription, message) do
  {:ok, _response} ->
    # Notification sent successfully
    :ok
  
  {:error, :expired} ->
    # Subscription expired or not found (HTTP 404 / 410)
    Repo.delete(subscription)
  
  {:error, {:http_error, status, body}} ->
    # Handle specific HTTP errors from the push service
    Logger.error("Push notification failed: HTTP #{status} - #{body}")
end

Common Web Push HTTP Status Codes

• 200-202: Success
• 404: Subscription not found
• 410: Subscription expired (user revoked permission)
• 400: Bad request (invalid parameters or VAPID headers)
• 401 / 403: Authentication error (check VAPID configuration)
• 413: Payload too large (max 3kB)
• 429: Rate limited (retry later)
• 500: Server error (retry later)

Run tests

mix test

License

Web Push Elixir is open-sourced software licensed under the MIT license.

Credits

Heavily inspired by elixir-web-push-encryption