Webhook + activation issues

“I paid but no licence email”

The most common cause: Polar’s webhook to Quay’s gateway hasn’t fired yet. Polar usually delivers webhooks within seconds, but delays of a few minutes happen.

Wait 5 minutes, then:

1. Check spam / junk for licence@uncle-z.com
2. Sign in to account.quay.uncle-z.com with the same email — the licence key + activation token are also visible in the Account → Devices page
3. Still nothing after 15 minutes — email zaid.ug@gmail.com with your Polar order ID (from the receipt Polar emailed). I can manually trigger the webhook.

”Activation says invalid licence key”

Three possible causes:

• Typo — the key is QUAY-XXXX-XXXX-XXXX-XXXX. Quay’s input field is case-insensitive and ignores spaces, but a missing dash or wrong character class breaks it.
• Wrong email — paste-into-portal vs paste-into-app — make sure the activate-here email matches the one that bought it.
• Already-revoked key — if you cancelled and re-bought, the old key no longer activates. Check Account → Billing for the current key.

”Activation says device limit reached”

Pro’s 1-slot cap or Pro Plus’ 3-slot cap is full. From the portal, go to Devices, revoke the slot you don’t need, and retry activation.

If every slot looks live but you only own one of those machines, the others might be ghost slots from previous installs. See Devices for the force-revoke flow.

”Webhook signature mismatch” (server-side)

This shouldn’t ever surface to you — it’s a gateway-side error. But if you’re poking at integrations and see it: the HMAC secret between Polar and Quay’s gateway, or between the gateway and the licence server, has rotated and the other side hasn’t picked up the new value. Email me; I’ll fix the rotation.

”Heartbeat failing — banner won’t go away”

The desktop app shows a banner if 3 consecutive heartbeats over 7 days fail. Most common causes:

• Corporate firewall / VPN — the licence server is at license.quay.uncle-z.com over HTTPS port 443. If the firewall blocks unknown TLS hosts, ask IT to whitelist that hostname.
• Clock skew — the activation token is JWT-style with a not-before and expires-at claim. If your machine’s clock is off by more than 5 minutes, the token validates server-side but the client refuses it. Sync your clock with NTP.
• Cached failure — Quay caches the last failure for 1 hour. Settings → Account → Retry now bypasses the cache.

”Token expired” while offline

The activation token is offline-valid for 30 days from the last successful heartbeat. If you’ve been offline 31+ days, Pro features lock until the next successful heartbeat.

Reconnect to internet, open Settings → Account → “Refresh licence” — Quay calls heartbeat, the token refreshes, and Pro features unlock.

”I changed my email — now activation fails”

Quay ties the activation token to the email at checkout. If you changed your email at the email-provider level (not via Quay’s portal), the licence key still works, but heartbeats start failing because the server can’t match the email to a live account.

For now, email me with the old + new addresses; v0.4 has a self-service email-change flow.

Reset everything

If activation is irrecoverable and you just want to start over:

# macOS
rm ~/Library/Application\ Support/com.unclez.quay/activation.json
security delete-generic-password -s "com.unclez.quay" 2>/dev/null

# Linux
rm ~/.config/quay/activation.json
secret-tool clear service com.unclez.quay 2>/dev/null

Re-launch Quay → re-paste the licence key. If the slot still shows “activated” on the server but the local copy is gone, that’s a ghost slot — see the force-revoke flow above.

Still stuck

Email zaid.ug@gmail.com with:

• The licence key (or the email you used at checkout)
• A screenshot of the error
• Your OS + Quay version (Settings → About)

I read every email; expect a reply within 24h.