Skip to Content
API ReferenceWebhooks

Webhooks

Elate HRMS uses Stripe webhooks to keep subscription data synchronized.

Stripe Webhook

POST /api/billing/webhook

This endpoint receives webhook events from Stripe. It is not authenticated via NextAuth — instead, it validates the Stripe webhook signature.

Handled Events

EventAction
checkout.session.completedProvisions new subscription and tenant database
customer.subscription.updatedUpdates plan, modules, and limits
customer.subscription.deletedMarks subscription as canceled
invoice.payment_succeededUpdates payment status
invoice.payment_failedMarks subscription as past due

What Happens on Subscription Change

When a subscription is created or updated, the webhook:

  1. Reads plan metadata from the Stripe Price object
  2. Updates the subscriptions table in the central database:
    • Plan name
    • Status (active, canceled, past_due, etc.)
    • Employee limit
    • ESS user limit
    • Active modules (from Price metadata)
    • Billing period dates
  3. For new subscriptions: provisions a new tenant database

Webhook Security

  • Stripe signature verification using STRIPE_WEBHOOK_SECRET
  • Rejects requests with invalid or missing signatures
  • Idempotent handling of duplicate events

Configuration

Set the webhook URL in your Stripe dashboard:

https://your-domain.com/api/billing/webhook

Required Stripe events to subscribe to:

  • checkout.session.completed
  • customer.subscription.updated
  • customer.subscription.deleted
  • invoice.payment_succeeded
  • invoice.payment_failed
Last updated on
Configuration