Razorpay Webhooks for Paid Membership Access

What a webhook does in a membership product

A webhook is a server-to-server notification. Razorpay sends an event when a payment, order, refund, or other supported object changes. The member does not have to keep the checkout tab open. This matters for paid WhatsApp groups because access, renewal, and refund actions may happen after the original browser flow ends.

A webhook is not the same as a redirect callback. The checkout callback helps an immediate user-facing flow. The webhook is an asynchronous provider message. Razorpay recommends webhooks as the primary automation mechanism and an API fetch when critical confirmation cannot wait for the event to arrive.

Choose events that change membership state

Subscribe only to events your system understands. A paid group workflow commonly cares about a paid order or captured payment, payment failure, and refund status. Do not grant access for an event that only means a payment was attempted. Map each provider event to a small set of allowed internal transitions.

For example, pending may become active after a verified captured payment. Active may become refunded after a matching completed refund. Failed should remain inactive. Record the provider event, current state, requested transition, and final result. This makes retries safe and gives support an audit trail.

• Order paid or captured payment: verify and activate once.
• Payment failed: record the attempt without access.
• Refund processed: update the payment and review access.
• Unknown event: log safely and take no membership action.

Validate the webhook signature correctly

Read the raw request body before parsing it and calculate the expected signature using the webhook secret configured in Razorpay. The webhook secret is separate from the Razorpay key secret. Compare signatures with a timing-safe method and reject invalid events before reading their business data.

Secret rotation needs care. Razorpay documentation notes that retried older requests may still require the secret active when the event was first sent. Plan a short rotation window if your implementation needs to accept retries created before the change. Never put the webhook secret in client-side code or source control.

Make retries harmless with idempotency

Webhook delivery is at least once, not exactly once. A provider can retry an event because your server timed out or returned an error. Store a provider event identifier or another stable deduplication key. Before changing membership state, check whether that event or payment has already been processed.

Use a database transaction for linked writes. Payment status, membership dates, refund state, access task, and audit record should either change together or fail together. If WhatsApp is temporarily unavailable, record a separate access task rather than rolling back a valid payment.

Monitor delivery, failures, and replay

Return a success response quickly after durable processing or queueing. Move slow work, such as WhatsApp access operations or emails, to a background task where possible. Monitor non-success responses and signature failures. Razorpay can disable a webhook after continued failures, so an unnoticed endpoint problem can stop membership updates.

Keep test and live endpoints separate, verify the expected mode, and review webhook history in the Razorpay Dashboard. For each incident, identify which event failed, whether it was replayed, and whether the membership reached the correct state. Do not replay events blindly without checking idempotency.