PlanGate
Type to search every docs page
↑ ↓ to move↵ to openesc to close
DocsSign in

Webhooks

PlanGate can tell your own server what happens in your app: a user pays, changes plan, cancels, runs out of budget, or signs in for the first time. Your server no longer has to ask /me to find out. Each event is a signed POST to an https address you choose.

You don't need a webhook to sell: PlanGate enforces plans and budgets itself. Add one when your backend keeps its own state, like a user's tier in your database, an email when someone upgrades, or a banner when a user hits a limit.

Set it up

  1. In the panel, open your app's Settings → Developers, then Webhook.
  2. Enter your endpoint's address and Save webhook. It must be a public https:// address.
  3. Copy the signing secret (whsec_…) into your server's configuration.
  4. Click Send a test. The panel shows how your endpoint answered.

New secret replaces the signing secret right away: the old one stops verifying. Remove stops all events. Events that happen while no webhook is set are not replayed later.

Events

Every request has a JSON body with the event's type, its timestamp and its data:

{
  "type": "subscription.activated",
  "timestamp": "2026-11-12T09:30:00Z",
  "data": {
    "app_id": "3f2a…",
    "user": {"id": "8c1d…", "external_id": "google-oauth2|1234", "email": "[email protected]"},
    "subscription": {
      "id": "sub_01J…",
      "channel": "polar",
      "status": "active",
      "plan": {"id": "b7e9…", "name": "Pro"},
      "ends_at": null,
      "expires_at": null,
      "pending_plan": null,
      "pending_at": null
    }
  }
}

user.id is the PlanGate id that /me returns. external_id is the sub of your own sign-in's token, when the app signs users in itself. email can be null.

Type When
subscription.activated A subscription starts serving: the first payment, or a new plan after an old one ended.
subscription.updated It still serves, but something changed: the plan (plan), a cheaper plan scheduled for the renewal (pending_plan, pending_at), a cancellation withdrawn, a renewal (expires_at), a payment problem (status).
subscription.canceled Cancelled at the end of the period: it keeps serving until ends_at.
subscription.expired It no longer serves: the period ended, the payment failed for good, or a store refunded or replaced it.
quota.exhausted A request was refused because the user ran out of budget. window is 5h, week or free_day, and resets_at is set for free_day. Sent at most once per window per user.
end_user.created A user signed in to your app for the first time.
webhook.test The panel's Send a test button.

channel is where the subscription is billed: polar, google_play, app_store or microsoft_store. status uses Polar's names: active, trialing, past_due, canceled, and so on.

New event types and new fields may be added. Ignore the ones you don't know.

Verify the signature

Each request carries three headers, following the Standard Webhooks specification:

  • webhook-id: the event's id, the same on every retry.
  • webhook-timestamp: when this attempt was sent, in seconds since 1970.
  • webhook-signature: v1, followed by the base64 HMAC-SHA256 of id.timestamp.body. The key is the base64 part of your secret, after whsec_.

Use a Standard Webhooks library, and pass it the raw body before any JSON parsing:

// npm install standardwebhooks
import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.PLANGATE_WEBHOOK_SECRET);

app.post("/plangate", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body, req.headers); // throws on a bad signature or an old timestamp
  } catch {
    return res.sendStatus(401);
  }
  // handle event.type, event.data
  res.sendStatus(204);
});
# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook

wh = Webhook(os.environ["PLANGATE_WEBHOOK_SECRET"])
event = wh.verify(request.get_data(), dict(request.headers))  # raises on a bad signature

Without a library, compute the signature yourself and compare it in constant time:

val key = Base64.getDecoder().decode(secret.removePrefix("whsec_"))
val mac = Mac.getInstance("HmacSHA256").apply { init(SecretKeySpec(key, "HmacSHA256")) }
val expected = "v1," + Base64.getEncoder().encodeToString(mac.doFinal("$id.$timestamp.$body".toByteArray()))
val valid = MessageDigest.isEqual(expected.toByteArray(), signatureHeader.toByteArray())

Also refuse a webhook-timestamp more than five minutes away from your clock. Otherwise someone who captured an old request could replay it.

Delivery and retries

  • Answer with any 2xx within 10 seconds. Anything else counts as a failure: another status, a timeout, a network error.
  • A failed event is sent again after 1 minute, then 2, 4, 8… up to every 6 hours, for about 20 hours in all. Each retry keeps the same webhook-id and gets a fresh timestamp and signature.
  • After the last failure, PlanGate drops the event and notifies you (push and email, as set in your notification settings).
  • Events can arrive twice, or out of order. Use webhook-id to skip duplicates. To know a user's current plan for sure, read /me when an event arrives.
  • Do slow work after answering: acknowledge first, then process the event.
❌🕸️