​
Webhooks

TurboStack provides webhook endpoints for handling events from Polar.sh.

​
Configuration

Add your webhook secret to .env: 
POLAR_WEBHOOK_SECRET=polar_ws_xxxxx
Configure the webhook URL in Polar Dashboard: 
https://your-api-domain.com/webhooks/polar

​
Handled Events

EventHandler
order.createdCreates order record
order.paidProvisions access, sends confirmation
order.refundedRevokes access
subscription.createdCreates subscription record
subscription.updatedUpdates subscription status
subscription.canceledRevokes premium access
checkout.createdLogs checkout start
product.created/updatedSyncs product data
customer.created/updatedSyncs customer data

​
Customizing Handlers

Edit apps/backend/src/services/polar.service.ts to add your business logic: 
function handleOrderPaid(data: unknown): WebhookResult {
  const order = data as { id: string; customerId?: string };

  // Add your logic here:
  // - Grant access to purchased content
  // - Send confirmation email
  // - Update database records

  return {
    success: true,
    message: "Order paid",
    eventType: "order.paid",
    data: { orderId: order.id },
  };
}

​
Testing Webhooks

​
Local Development

Use a tool like ngrok to expose your local server: 
ngrok http 4101
Then use the ngrok URL in Polar dashboard.

​
Send Test Events

Polar dashboard allows sending test webhook events to verify your integration.

​
Security

Webhooks are verified using HMAC signatures. The validateWebhookEvent function automatically verifies the signature before processing any event.