API ReferenceIntegrationsKnowledge Base

Notifications

There are two types of notifications you receive from Razorpay for subscriptions, emails and webhooks.

Emails#

Emails are sent to your customers at various important events such as:

  • The start of the subscription.
  • When a payment is successfully charged.
  • When a payment fails.
  • Action required by the customer in the event of a payment failure
  • When the card linked to a subscription is changed or updated.
  • When the details of a subscription (such as plan, quantity and/or billing frequency) are updated.

Types of Emails#

Razorpay sends emails to customers at 8 different stages during the life of a subscription. These are:

Created
This email is sent only in the case of Subscriptions via Links. This email is sent when you create and send a new subscription link to a customer for them to make the authentication payment. The authenticated amount depends on the upfront_amount for the subscriptions.
Initialized
This email is sent after the customer successfully makes the authentication payment.
Charged Successfully
This email is sent when we make a successful automated charge on the subscription as per the billing cycle.
Completed
This email is sent to the customer when the subscription moves to completed state. There is no completed email sent if the subscription moves from the completed state to the completed state. This is because the subscription is already completed and a charge was made on an older invoice.
Charged Failed
This email is sent when a charge on a card fails. When an automated charge on a subscription fails, we retry an auto-charge on the card. If the retries have not been exhausted, the subscription moves to the pending state. We send out an email every time the subscription moves to the pending state. The email contains an Update Card option that allows the customer to change the card linked to the subscription.
Card Updated
This email is sent whenever a customer changes the card linked to the subscription. This email notifies the customer that their card has been successfully changed and that the new card details are now associated with the subscription.
Invoice Charge
This email is sent when a manual charge is made on an old invoice of the subscription (either by you or the customer). If the subscription was in the halted state when the manual charge was done, we also mention that the subscription is now active and we would resume the automated charges from the next cycle onwards in the email.
Halted
When an automated charge on a subscription fails, we retry an auto-charge on the card. When all the retries are exhausted, it moves to the halted state. We send out an email every time the subscription moves to the halted state. The email contains the Update Card option to change the card linked to the subscription.
Cancelled
This email is sent when the subscription moves to cancelled state. This could be because you or the customer canceled the subscription.
Subscription Updated
This email is sent when the subscription is successfully updated. There is no state change when a subscription is updated.

Webhooks#

Webhooks allow you to build or set up integrations that subscribe to certain events on Razorpay APIs. When one of those events is triggered, we send an HTTP POST payload in JSON to the webhook's configured URL.

You can set up webhooks from your Dashboard and configure separate URLs for live mode and test mode.

A test mode webhook will only receive events for your test transactions.

In URLs, only port numbers 80 and 443 are currently allowed.

When setting up the webhook, you will be asked to specify a secret. Using this secret, you can validate that the webhook is from Razorpay. Entering the secret is optional, but recommended. The secret should never be exposed publicly.

Idempotency#

To avoid an event being missed, Razorpay follows at-least-once delivery semantics. In this approach, if we do not receive a successful response from your server, we resend the Webhook.

There could be situations where your server accepts the event but fails to return a response in 5 seconds. In such cases, the session is marked timeout. It is assumed that the Webhook has not been processed and is sent again. Ensure your server is configured to handle or receive the same event details multiple times.

Check the value of x-razorpay-event-id in the webhook request header. The value for this header is unique per event and can help you determine the duplicity of a webhook event.

Deactivation#

All webhook responses must return a status code in the range 2XX within a window of 5 seconds. If we receive response codes other than this or if the request times out, it is considered a failure.

On failure, a Webhook is retried at progressive intervals of time, defined in the exponential backoff policy, for 24 hours. If the failures persist for 24 hours, the webhook is disabled. You will then need to re-enable the Webhook from the Dashboard after fixing the errors at your end.

Note:
Razorpay will send you an email notification when a webhook gets disabled due to multiple failures.

Setup Webhooks#

You can set up multiple URLs to receive webhook notifications.

To setup webhooks:

  1. Log into your Razorpay Dashboard and navigate to SettingsWebhooks.
  2. Click + Add New Webhook.
  3. In the Webhook Setup modal:
    1. Enter the URL where you want to receive the webhook payload when an event is triggered. We recommended using an HTTPS URL.
    2. Enter a Secret for the webhook endpoint. The secret is used to validate that the webhook is from Razorpay. Do not expose the secret publicly. Learn more about Webhook Secret.
    3. In the Alert Email field, enter the email address to which notifications must be sent in case of webhook failure.
    4. Select the required events from the list of Active Events. Sample payloads for all events are available.
  4. Click Create Webhook.

Once created, it appears on the list of webhooks:

Watch the short animation below for more details.

Available Events#

The table below lists the webhook events available for Subscriptions.

Note:
The payload for all these events would contain the subscription entity. They also contain a payment entity if a payment attempt was made before the event was triggered.

Webhook Event
Description
subscription.authenticated
Sent when the first payment is made on the subscription. This can either be the authorization amount, the upfront amount, the plan amount or a combination of the plan amount and the upfront amount.
subscription.activated
Sent when the subscription moves to the active state either from the authenticated, pending or halted state. If a subscription moves to the active state from the pending or halted state, only the subsequent invoices that are generated are charged. Existing invoices that were already generated are not charged.
subscription.charged
Sent every time a successful charge is made on the subscription.
subscription.completed
Sent when all the invoices are generated for a subscription and the subscription moves to the completed state.
subscription.updated
Sent when a subscription is successfully updated. There is no state change when a subscription is updated.
subscription.pending
Sent when the subscription moves to the pending state. This happens when a charge on the card fails. We try to charge the card on a periodic basis while it is in the pending state. If the payment fails again, the webhook is triggered again.
subscription.halted
Sent when all retries have been exhausted and the subscription moves from the pending state to the halted state. The customer has to manually retry the charge or change the card linked to the subscription, for the subscription to move back to the active state.
subscription.cancelled
Sent when a subscription is cancelled and the subscription moves to the cancelled state.
subscription.paused
Sent when a subscription is paused and the subscription moves to the paused state.
subscription.resumed
Sent when a subscription is unpaused and the subscription moves to the resumed state.

Sample Payloads#

For sample payloads, refer to the Sample payload section in the API portion of this document.