Agent skill

Polar Webhooks Skill

Receive and verify Polar webhooks. Use when setting up Polar webhook handlers, debugging Standard Webhooks signature verification, or handling billing events like order.paid, subscription.created, subscription.canceled, or checkout.updated.

Install this skill

npx skills add hookdeck/webhook-skills --skill polar-webhooks

When to Use This Skill

How do I receive Polar webhooks?
How do I verify Polar webhook signatures?
How do I handle order.paid, subscription.created, or checkout.updated events?
Why is my Polar webhook signature verification failing?
Setting up a Polar webhook endpoint in organization settings

Verification (core)

Polar follows the Standard Webhooks spec. Each request carries three headers — webhook-id, webhook-timestamp, and webhook-signature — and the signature is an HMAC-SHA256, base64-encoded, over {webhook-id}.{webhook-timestamp}.{body}. Always verify against the raw request body — don't JSON.parse first.

Use Polar's official SDK helpers, which parse and verify in one call:

Node (@polar-sh/sdk):

const { validateEvent, WebhookVerificationError } = require('@polar-sh/sdk/webhooks');

try {
  // rawBody: Buffer/string of the raw HTTP body; headers: the request headers object
  const event = validateEvent(rawBody, headers, process.env.POLAR_WEBHOOK_SECRET);
  // event.type -> e.g. "order.paid"; event.data -> the resource
} catch (err) {
  if (err instanceof WebhookVerificationError) {
    // invalid signature -> respond 400/403
  }
}

Python (polar-sdk):

from polar_sdk.webhooks import validate_event, WebhookVerificationError

try:
    event = validate_event(body=raw_body, headers=request.headers,
                           secret=os.environ["POLAR_WEBHOOK_SECRET"])
except WebhookVerificationError:
    ...  # invalid signature -> respond 400/403

Secret gotcha: The Standard Webhooks spec expects the secret to be base64-encoded before signing. The Polar SDKs base64-encode your dashboard secret for you, so pass the secret as-is. For a manual verifier, base64-encode the secret first (see references/verification.md). Polar secrets are user-set or randomly generated — they are not whsec_-prefixed.

For complete handlers with route wiring, event dispatch, and tests, see:
examples/express/
examples/nextjs/
examples/fastapi/

Common Event Types

Event	Triggered When
`checkout.updated`	A checkout session changes state (e.g. confirmed)
`order.created`	A new order is created (purchase or subscription renewal)
`order.paid`	An order is fully paid
`order.refunded`	An order is refunded
`subscription.created`	A new subscription is created
`subscription.canceled`	A subscription is set to cancel at period end
`subscription.revoked`	A subscription ends and access should be revoked
`customer.state_changed`	A customer's state changes (subscriptions/benefits)

For the full list of 30+ events, see Polar Webhook Events.

Environment Variables

POLAR_WEBHOOK_SECRET=your_webhook_signing_secret   # From the endpoint settings in Polar

Local Development

# Start a tunnel to your local handler (no account needed)
npx hookdeck-cli listen 3000 polar --path /webhooks/polar

Polar also ships a first-party tunnel: polar listen http://localhost:3000/, and a sandbox environment (sandbox.polar.sh) for test purchases without real charges.

Reference Materials

references/overview.md - What Polar webhooks are, common events
references/setup.md - Dashboard configuration and signing secret
references/verification.md - Signature verification details and gotchas