Subscription links

A subscription link lets other people get your notifications in their own PushBell app: order updates for your customers, server alerts for your users, announcements for your subscribers. Whoever opens the link signs in with their PushBell account, taps Subscribe, and a subscribed key (u_…) specific to your project is created. Their email and own user key aren’t shared with you. They can leave anytime from Settings → My subscriptions in the app.

Link kinds

In the dashboard, on your project’s Subscribers tab, click New link:

• Group: the subscriber is added to the group you pick. Send to the group’s key and it reaches everyone. For announcements and “everyone gets it” notifications.
• Web: after subscribing, the browser returns to the Success URL with a pushbell_user_key parameter (pushover_user_key comes too, for Pushover compatibility). Store the key with your user record and send to that person with to. For personal notifications (e.g. “your order has shipped”).

Links look like https://app.pushbell.app/subscribe/…. The dashboard gives you the link’s QR code (PNG) and the code for a Subscribe with PushBell button for your site. On a phone with the app installed, the link opens right in the app.

{ "title": "Your order has shipped", "message": "Tracking: 1Z999", "to": ["u_their_subscribed_key"] }

If the same person opens the link again and subscribes, they get the same key. How many subscribers you can have depends on your plan.

Security for web links

Anyone could also send a key to your success URL with a forged request. To prevent that:

1. Store a random state value in the visitor’s session.
2. Pass your own return URL to the link as the success parameter (URL-encoded); it must start with the link’s success URL: https://app.pushbell.app/subscribe/CODE?success=https%3A%2F%2Fexample.com%2Fpushbell%3Fstate%3DX7f2.
3. On return, compare state with the one in the session; if it doesn’t match, don’t store the key.

Unsubscribing

• If the person leaves from My subscriptions in the app, their key stops working and they drop out of the group a group link added them to.
• If they open a web link again and tap Unsubscribe, the browser returns to the success URL with an empty pushbell_user_key, pushover_unsubscribed=1 and pushover_unsubscribed_user_key=<the old key>.
• You can also remove a subscriber in the dashboard.

Give the link an Event URL and subscribe and unsubscribe events arrive there as signed POSTs (webhook signature), retried for up to 24 hours:

{ "event": "subscriber.subscribed", "project_id": "…", "link_id": "…", "subscribed_key": "u_…", "at": 1793057112 }

On unsubscribe, event is subscriber.unsubscribed.

Migrating existing keys

If you collected people’s own user keys before using subscription links, turn each into a project-specific subscribed key:

curl -X POST https://api.pushbell.app/v1/subscriptions/migrate \
  -H "Authorization: Bearer pb_live_…" -H "Content-Type: application/json" \
  -d '{"subscription": "LINK_CODE", "user": "u_their_own_key"}'

Store the subscribed_key from the response instead of the user key; the person can now unsubscribe from their app. As with Pushover, POST /1/subscriptions/migrate.json (token, subscription, user) works too.